LabelingData

Specifies custom data for the GenericLabeling.

Inheritance Hierarchy

LabelingData

Examples

The following example shows how to create a new instance of LabelingData and use it with a GenericLabeling:

Creating an instance of LabelingData

const layoutData = new LabelingData()
layoutData.affectedLabels = graphComponent.selection.selectedLabels
layoutData.edgeLabelPreferredPlacement = (label) =>
  new PreferredPlacementDescriptor({
    // Place short labels horizontally, and others along the edge
    angleReference:
      label.text.length < 5
        ? LabelAngleReferences.ABSOLUTE
        : LabelAngleReferences.RELATIVE_TO_EDGE_FLOW
  })

graphComponent.graph.applyLayout(new GenericLabeling(), layoutData)const layoutData = new LabelingData()
layoutData.affectedLabels = graphComponent.selection.selectedLabels
layoutData.edgeLabelPreferredPlacement = (
  label: ILabel
): PreferredPlacementDescriptor =>
  new PreferredPlacementDescriptor({
    // Place short labels horizontally, and others along the edge
    angleReference:
      label.text.length < 5
        ? LabelAngleReferences.ABSOLUTE
        : LabelAngleReferences.RELATIVE_TO_EDGE_FLOW
  })

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

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

Using an object initializer for easy creation of LabelingData

const layoutData = new LabelingData({
  affectedLabels: graphComponent.selection.selectedLabels,
  edgeLabelPreferredPlacement: (label) =>
    new PreferredPlacementDescriptor({
      // Place short labels horizontally, and others along the edge
      angleReference:
        label.text.length < 5
          ? LabelAngleReferences.ABSOLUTE
          : LabelAngleReferences.RELATIVE_TO_EDGE_FLOW
    })
})

graphComponent.graph.applyLayout(new GenericLabeling(), layoutData)const layoutData = new LabelingData({
  affectedLabels: graphComponent.selection.selectedLabels,
  edgeLabelPreferredPlacement: (
    label: ILabel
  ): PreferredPlacementDescriptor =>
    new PreferredPlacementDescriptor({
      // Place short labels horizontally, and others along the edge
      angleReference:
        label.text.length < 5
          ? LabelAngleReferences.ABSOLUTE
          : LabelAngleReferences.RELATIVE_TO_EDGE_FLOW
    })
})

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

Type Details

yfiles module: view-layout-bridge
yfiles-umd modules: view-layout-bridge
Legacy UMD name: yfiles.labeling.LabelingData

Constructors

LabelingData

()

Creates a new instance of LabelingData which helps configuring GenericLabeling.

ParametersOptions Overload

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

affectedLabels - DpKeyItemCollection<ILabel>: The collection of labels that shall be placed by the algorithm. This option sets the affectedLabels property on the created object.
nodeLabelModels - ItemMapping<ILabel,INodeLabelLayoutModel>: The mapping from node labels to an INodeLabelLayoutModel used by the labeling algorithm instead of the original label model. This option sets the nodeLabelModels property on the created object.
edgeLabelModels - ItemMapping<ILabel,IEdgeLabelLayoutModel>: The mapping from edge labels to an IEdgeLabelLayoutModel used by the labeling algorithm instead of the original label model. This option sets the edgeLabelModels property on the created object.
sourceGroupIds - ItemMapping<IEdge,Object>: A mapping from edges to an object representing their source edge group. This option sets the sourceGroupIds property on the created object.
targetGroupIds - ItemMapping<IEdge,Object>: A mapping from edges to an object representing their target edge group. This option sets the targetGroupIds 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.
edgeLabelPreferredPlacement - ItemMapping<ILabel,PreferredPlacementDescriptor>: The mapping that provides a PreferredPlacementDescriptor instance for edge ILabels. This option sets the edgeLabelPreferredPlacement 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

affectedLabels

: DpKeyItemCollection<ILabel>

Gets or sets the collection of labels that shall be placed by the algorithm.

Remarks

Note that the dpKey has to be set to the key assigned to affectedLabelsDpKey.

Examples

Defining the subset of labels that should be laid out can be done in various ways, mostly depending on which option is more convenient for a particular use case. You can use the ItemCollection<TItem>'s source property to use any .NET collection or IEnumerable<T>:

Setting a collection of affected nodes

layoutData.affectedLabels = graphComponent.selection.selectedLabels
labelingAlgorithm.affectedLabelsDpKey = layoutData.affectedLabels.dpKey =
  selectedLabelsKey

Alternatively, ItemCollection<TItem> also has an items property, which is a collection that already exists, in case the items may have to be added one by one. This can be more convenient than defining an own list and setting it to source:

Adding individual nodes as affected nodes

layoutData.affectedLabels.items.add(label1)
layoutData.affectedLabels.items.add(label2)
labelingAlgorithm.affectedLabelsDpKey = layoutData.affectedLabels.dpKey =
  selectedLabelsKey

A powerful option that doesn't use a collection is to use the delegate to set a custom delegate that returns for every node whether it is contained in the set or not:

Using a delegate to determine whether a node is affected or not

// We assume here that all labels have a CustomData instance as their Tag,
// which then has a boolean property 'IncludeInLayout'.
layoutData.affectedLabels = (label) => label.tag.includeInLayout
labelingAlgorithm.affectedLabelsDpKey = layoutData.affectedLabels.dpKey =
  selectedLabelsKey// We assume here that all labels have a CustomData instance as their Tag,
// which then has a boolean property 'IncludeInLayout'.
layoutData.affectedLabels = (label: ILabel): boolean =>
  label.tag.includeInLayout
labelingAlgorithm.affectedLabelsDpKey = layoutData.affectedLabels.dpKey =
  selectedLabelsKey

edgeLabelModels

: ItemMapping<ILabel,IEdgeLabelLayoutModel>

Gets or sets the mapping from edge labels to an IEdgeLabelLayoutModel used by the labeling algorithm instead of the original label model.

Remarks

If a label has no mapping, the original model is used as normal.

A model parameter that fits the calculated position of the replacement model best is set for the original label model.

This feature is especially useful to restrict a free model. For example, to place a label upon its associated edge, a centered SliderEdgeLabelLayoutModel can be used as replacement model.

Examples

Specifying a custom label model for edge labels can be done in different ways, depending on which option is the most convenient for a given use case. If only a few labels must be customized in this way and most should be left alone, using the mapper is usually the easiest option:

Using a mapper to specify a different label model for certain labels

// Place label1 at the source side on the edge
layoutData.edgeLabelModels.mapper.set(
  label1,
  new DiscreteEdgeLabelLayoutModel(DiscreteEdgeLabelPositions.SOURCE_CENTER)
)
// Place label2 somewhere along the side of the edge
layoutData.edgeLabelModels.mapper.set(
  label2,
  new SliderEdgeLabelLayoutModel(SliderMode.SIDE)
)
// All other labels not explicitly configured follow their respective ILabelModel and its valid parameters

When the label model to use is easy to determine from each label itself, using a delegate is often easier:

Using a delegate to specify a label model for each label

layoutData.edgeLabelModels = (label) => {
  const customData = label.tag
  // Place labels with a special property in their tag in the center
  // of their edge and place all others as usual.
  return customData.placeInCenter
    ? new DiscreteEdgeLabelLayoutModel(DiscreteEdgeLabelPositions.CENTER)
    : null
}layoutData.edgeLabelModels = (label: ILabel): IEdgeLabelLayoutModel => {
  const customData = label.tag
  // Place labels with a special property in their tag in the center
  // of their edge and place all others as usual.
  return customData.placeInCenter
    ? new DiscreteEdgeLabelLayoutModel(DiscreteEdgeLabelPositions.CENTER)
    : null!
}

Finally, to override the default behavior in the same way for every single label, a constant could also be used:

Specifying the same label model for all edge labels

layoutData.edgeLabelModels.constant = new SliderEdgeLabelLayoutModel(
  SliderMode.CENTER
)

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
  )

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

nodeLabelModels

: ItemMapping<ILabel,INodeLabelLayoutModel>

Gets or sets the mapping from node labels to an INodeLabelLayoutModel used by the labeling algorithm instead of the original label model.

Remarks

If a label has no mapping, the original model is used as normal.

A model parameter that fits the calculated position of the replacement model best is set for the original label model.

This feature is especially useful to restrict a free model. For example, to place a label upon its associated node, a centered DiscreteNodeLabelLayoutModel can be used as replacement model.

Examples

Specifying a custom label model for node labels can be done in different ways, depending on which option is the most convenient for a given use case. If only a few labels must be customized in this way and most should be left alone, using the mapper is usually the easiest option:

Using a mapper to specify a different label model for certain labels

// Place label1 either above or below the node
layoutData.nodeLabelModels.mapper.set(
  label1,
  new DiscreteNodeLabelLayoutModel(
    DiscreteNodeLabelPositions.NORTH | DiscreteNodeLabelPositions.SOUTH
  )
)
// Place label2 in the center of the node
layoutData.nodeLabelModels.mapper.set(
  label2,
  new DiscreteNodeLabelLayoutModel(DiscreteNodeLabelPositions.CENTER)
)
// All other labels not explicitly configured follow their respective ILabelModel and its valid parameters

When the label model to use is easy to determine from each label itself, using a delegate is often easier:

Using a delegate to specify a label model for each label

layoutData.nodeLabelModels = (label) => {
  const customData = label.tag
  // Place labels with a special property in their tag in the center
  // of their node and place all others as usual.
  return customData.placeInCenter
    ? new DiscreteNodeLabelLayoutModel(DiscreteNodeLabelPositions.CENTER)
    : null
}layoutData.nodeLabelModels = (label: ILabel): INodeLabelLayoutModel => {
  const customData = label.tag
  // Place labels with a special property in their tag in the center
  // of their node and place all others as usual.
  return customData.placeInCenter
    ? new DiscreteNodeLabelLayoutModel(DiscreteNodeLabelPositions.CENTER)
    : null!
}

Finally, to override the default behavior in the same way for every single label, a constant could also be used:

Specifying the same label model for all node labels

layoutData.nodeLabelModels.constant = new DiscreteNodeLabelLayoutModel(
  DiscreteNodeLabelPositions.BOTTOM |
    DiscreteNodeLabelPositions.BOTTOM_LEFT |
    DiscreteNodeLabelPositions.BOTTOM_RIGHT
)

sourceGroupIds

: ItemMapping<IEdge,any>

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

Remarks

Source and target edge groups are only used for labeling in conjunction with the edgeGroupOverlapAllowed setting where a label may overlap an edge from the same group. Edges don't have to share parts of the same path for this purpose (as would be the result from other layout algorithms that use edge grouping). Specifying source and target groups will not change edge paths, nor will the labels be placed any different. It is mainly a tool to allow selective label/edge overlaps in certain cases.

targetGroupIds

: ItemMapping<IEdge,any>

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

Remarks

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

LabelingData

Examples

Type Details

See Also

Constructors

LabelingData

ParametersOptions Overload

Properties

abortHandler

Remarks

Examples

See Also

affectedLabels

Remarks

Examples

See Also

edgeLabelModels

Remarks

Examples

See Also

edgeLabelPreferredPlacement

Examples

See Also

nodeHalos

Remarks

Examples

See Also

nodeLabelModels

Remarks

Examples

See Also

sourceGroupIds

Remarks

See Also

targetGroupIds

Remarks

See Also

Methods

combineWith

Remarks

Parameters

Returns

See Also

Defined in