Generic labeling is independent of any layout algorithms and can be applied to any kind of diagram. It generates label placements without altering node positions, node sizes, or edge paths.

Integrated labeling, in contrast, is directly provided by some layout algorithms as an integrated part of the layout calculation. It allows to consider labels as part of the overall layout.

Integrated labeling's advantage is that, by design, it can prevent label overlaps completely. Generic labeling cannot always achieve this, since it has to deal with the existing node positions, node sizes, and edge paths. However, the graph's dimensions will remain constant or grow only minimally with generic labeling.

Additionally, generic labeling also supports placement of rotated labels, which covers both maintaining a preset rotation angle as well as finding edge label positions where the rotation is determined by the labeling algorithm, too.

Both node label and edge label have associated a so-called "label model," that defines a set of valid positions where the label can be placed relative to its respective graph element. In the context of automatic label placement, all valid positions are at the same time "candidates" among which a labeling algorithm can choose the best match to ultimately place the label.

For both generic labeling as well as integrated edge labeling, labels and label models are set up using the API provided by IGraph. See also the Label Support section in the yFiles FLEX Developer's Guide.

For generic labeling around a node, FreeNodeLabelModel is a much better choice for a node label model than any of the discrete node label models. However, FreeNodeLabelModel allows for unspecified label positions only, while the positions of the discrete node label models are all predefined.

For generic labeling, FreeEdgeLabelModel or SmartEdgeLabelModel with their large number of nearly continuous positions is the best choice for an edge label model, followed by the slider edge label models.

Integrated labeling also favors FreeEdgeLabelModel or SmartEdgeLabelModel, followed by the slider edge label models, since it does not work with the candidates initially. Instead, it first computes an optimal location for the label, and then tries to find the best matching label position for that location in the given label model.

Class PreferredPlacementDescriptor can be used to configure preferred placement options and preferred rotation behavior for edge labels. When calculating edge label positions, the specified settings will be adhered to as good as possible by both the generic labeling algorithms as well as the layout algorithms that support integrated labeling.

Preferred placement options include, for example, whether an edge label shall be positioned

Preferred rotation behavior includes, for example, whether

The edge label configurations supported by class PreferredPlacementDescriptor only make sense when the edge label is associated with a label model that supports label rotation and that does not restrict edge label placement to discrete positions. In particular, this applies to the "free" label models FreeEdgeLabelModel or SmartEdgeLabelModel, but also to the slider edge label models.

The following property defined in interface EdgeLabelLayout returns the PreferredPlacementDescriptor instance that is associated with an edge label:

preferredPlacementDescriptor:PreferredPlacementDescriptor

By default, the PreferredPlacementDescriptor instance that is associated with actual implementations of interface IEdgeLabelLayout, like, e.g., instances of class EdgeLabelLayoutImpl, is immutable. The immutability is a direct consequence of the descriptor instance being shared among newly created edge labels.

To properly configure individual preferred placement options for an edge label, a dedicated descriptor instance needs to be associated with the label. The following code snippet shows how this can be achieved:

// 'ell' is of type com.yworks.yfiles.layout.EdgeLabelLayoutImpl.

// Create a copy of the edge label's current descriptor using the copy 
// constructor of the class.
var prefPDesc:PreferredPlacementDescriptor = 
    new PreferredPlacementDescriptor(ell.preferredPlacementDescriptor);
// Now configure individual preferred placement options on the copy.
...

// Make it immutable (optional).
prefPDesc.freeze();

// Set the copy as the descriptor for the new edge label.
ell.preferredPlacementDescriptor = prefPDesc;

The properties of class PreferredPlacementDescriptor to configure preferred placement options are:

sideOfEdge:LabelAngleOnRightSideOffset
sideReference:LabelAngleReference
distanceToEdge:double
placeAlongEdge:LabelSideReference

An edge label can be placed at the side of the path of its edge. The actual side can be specified both absolute and relative:

Figure 5.115. Absolute and relative edge label placement

Absolute placement: left of the edge path when looking at the diagram.	Relative placement: left of the edge path when looking from source to target along the edge path.

Note that the sideReference property provides the means to resolve the special case when the edge label's side is specified as an absolute placement and its corresponding edge segment happens to be horizontal, i.e., when there is no actual left or right "side."

The properties to configure preferred rotation behavior:

angle:double
angleReference:LabelAngleReference
angleRotationOnRightSide:LabelAngleOnRightSideRotation

The arrow-shaped gradient in the background of the label denotes the orientation of its box. Note that in the right figure below the text of the left label is flipped: according to its box's orientation, the text would actually be upside-down, but to be readable it is automatically rendered correctly.

Figure 5.116. Absolute and relative edge label rotation

Absolute rotation: 0 degree when looking at the diagram.	Relative rotation: 0 degree added to the slope of the edge segment that is nearest to the edge label.

A generic labeling algorithm computes label positions for the labels from a given graph so that they, ideally, do not overlap with each other or with graph elements. It does so without altering nodes or edges in any way. Figure 5.117, “Class hierarchy for labeling algorithms” shows the class hierarchy of the generic labeling algorithms that are provided in package y.layout.labeling.

Figure 5.117. Class hierarchy for labeling algorithms

The set of labels that a generic labeling algorithm processes can be restricted to node labels only or to edge labels only:

placeNodeLabels:Boolean
placeEdgeLabels:Boolean

Optionally, they can also be configured to auto-flip edge labels to avoid that their text is upside-down:

autoFlippingEnabled:Boolean

The labeling algorithm uses the model that is associated with a label to get the available candidate positions. From this set of candidates it then chooses one that best matches the label position it has calculated. The label model's model parameter is then used to encode this position.

It is important to understand that the result of a labeling algorithm is one model parameter per processed label, which is directly stored with the label after calculation. This model parameter expresses the calculated label position with respect to the corresponding label model, and it is only valid in the context of this label model. To get the actual location of a label after the labeling algorithm has finished, both model parameter and corresponding label model are necessary.

The base class for all major layout algorithms, class CanonicMultiStageLayouter, allows to conveniently enable/disable generic labeling for each layout run. The labeling algorithm is then invoked after the actual layout algorithm has finished. Additionally, the labeling algorithm itself can also be set. Class CanonicMultiStageLayouter provides the following labeling-related properties:

labelLayouterEnabled:Boolean

labelLayouter:LayoutStage

Generic labeling is set up using the label layout layout stage support provided by the base class of the layout algorithms, class CanonicMultiStageLayouter:

var ihl:IncrementalHierarchicLayouter = new IncrementalHierarchicLayouter();

// Setting up generic edge labeling.
var labeler:AbstractLabelingAlgorithm = new GreedyMISLabeling();
labeler.placeNodeLabels = false;
ihl.labelLayouter = labeler;
ihl.labelLayouterEnabled = true;

// A mapper implementation that returns for each edge label the label model
// that shall be used by the labeling algorithm.
public class MyAlternateLabelModelMapper implements IMapper {
  var elm:EdgeLabelModel = new RotatedSliderEdgeLabelLayoutModel(
                               RotatedSliderEdgeLabelLayoutModel.CENTER_SLIDER);
  
  function MyAlternateLabelModelMapper() {}
  
  public function lookupValue(key:Object):Object {
    if (key is EdgeLabelLayout) {
      var currELM:EdgeLabelModel = EdgeLabelLayout(key).labelModel;
      if (currELM is FreeEdgeLabelLayoutModel) {
        return elm;
      }
    }
    // Means that the label's actual label model is used.
    return null;
  }
  
  public function mapValue(key:Object, value:Object):void {}
  public function unMapValue(key:Object):void {}
}

// 'graph' is of type com.yworks.graph.model.IGraph.

// Add the mapper to the mapper registry of the graph.
// Use the "well-known" look-up key defined in class AbstractLabelingAlgorithm 
// as tag.
graph.mapperRegistry.addMapper(AbstractLabelingAlgorithm.LABEL_MODEL_DPKEY, 
                               new MyAlternateLabelModelMapper());

Supplemental Layout Data

The generic labeling algorithms know a number of data provider keys which are used to retrieve supplemental layout data for the labels in a graph. The data is bound to the graph by means of a data provider which is registered using a given look-up key. Table 5.86, “Data provider look-up keys” lists all look-up keys that a generic labeling algorithm tests during the layout process in order to query supplemental data.

Binding supplemental layout data to a graph is described in the section called “Providing Supplemental Layout Data”.

Table 5.86. Data provider look-up keys

Key	Element Type	Value Type	Description
LABEL_MODEL_DPKEY	INodeLabelLayout	INodeLabelModel	For each INodeLabelLayout instance an INodeLabelModel instance that is used to determine valid label positions.
	IEdgeLabelLayout	IEdgeLabelModel	For each IEdgeLabelLayout instance an IEdgeLabelModel instance that is used to determine valid label positions.

Integrated labeling denotes automatic edge label placement as an integrated part of a layout algorithm. All edge labels of a graph are arranged in such a manner that there are no overlaps of edge labels with each other or with graph elements.

Table 5.87, “Layout support for integrated labeling” lists the major layout algorithms that provide support for integrated labeling.

Table 5.87. Layout support for integrated labeling

Layout Style	Classname	Note
Hierarchical	IncrementalHierarchicLayouter	With class IncrementalHierarchicLayouter, integrated labeling can be conveniently enabled using appropriate configuration properties. See the description of the hierarchical layout style for more information.
Orthogonal	OrthogonalLayouter, DirectedOrthogonalLayouter, and OrthogonalGroupLayouter	See the descriptions of orthogonal layout, directed orthogonal layout, and orthogonal layout of grouped graphs for more information.
Tree	TreeLayouter, GenericTreeLayouter, and BalloonLayouter	Integrated labeling can conveniently be enabled using appropriate configuration properties. See the descriptions of directed tree layout, generic tree layout, and balloon layout for more information.

Integrated labeling is most conveniently triggered using the corresponding properties of the layout algorithms that support it. For example:

var ihl:IncrementalHierarchicLayouter = new IncrementalHierarchicLayouter();

// Enabling integrated edge labeling.
ihl.integratedEdgeLabeling = true;

Example 5.43, “Using class LabelLayoutTranslator” shows how to configure integrated labeling in the absence of an appropriate configuration property using LabelLayoutTranslator. This class converts label layout information so that it is understood by a layout algorithm.

function useIntegratedLabeling(layouter:CanonicMultiStageLayouter):void {
  // Use integrated labeling support, and let class LabelLayoutTranslator do
  // the conversion of information held by an edge label's EdgeLabelLayout
  // object to data provider-based information that is understood by the
  // algorithm.
  layouter.labelLayouter = new LabelLayoutTranslator();
  layouter.labelLayouterEnabled = true;
}

Through the following property LabelLayoutTranslator supports configuration of edge label auto-flip behavior:

autoFlippingEnabled:Boolean