skip to main content
Programmer's documentation > Using graph layout algorithms > Automatic label placement > Specifying labels and obstacles
 
Specifying labels and obstacles
Explains what labels and obstacles are.
*Labels and obstacles in a diagram component
*Presents labels and obstacles and discusses how labels for different objects are positioned.
*Labels and obstacles in Java
*Describes how to specify labels and obstacles when working directly on an IlvManager object in Java™.
Labels and obstacles in a diagram component
Rogue Wave®  JViews Diagrammer uses an SDM data model that distinguishes between nodes and links. Labels can belong to nodes or to links. The label layout considers the nodes and links themselves as obstacles. However, only nodes of type IlvGeneralNode and IlvSDMCompositeNode, and only links of type IlvGeneralLink and IlvSDMCompositeLink. can have labels.
Labels at nodes
Each instance of IlvGeneralNode has at most one label. This label can be placed by a hard-coded mechanism of IlvGeneralNode which does not take into account the free space, or it can be placed by the label layout renderer. The parameter labelPosition of the class IlvGeneralNode enables you to indicate how the label is placed. If the label position is set to:
*Center ”: the label is placed by the hard-coded mechanism at the center of the node. It is not taken into account by the label layout.
*Left ”, “ Right ”, “ Top ”, “ Bottom ”: the label is placed by the label layout renderer if the label layout renderer is enabled, otherwise it is placed by the IlvGeneralNode hard-coded mechanism.
The label can be implemented internally by the class IlvZoomableLabel or IlvText and can be specified as zoomable or scaled relative to the node size. See the following sample specification of a node with a label:
 
node {
    class: "ilog.views.sdm.graphic.IlvGeneralNode";
    label: "@name";
    labelScaleFactor: "0.5";
    labelFont: "PLAIN-BOLD-12";
    labelAntialiasing: "true";
    labelZoomable: "true";
    useIlvText: "true";
 
    labelPosition: "Left";
    labelSpacing: "2.0";
}
This node uses the class IlvGeneralNode with a label of type IlvText. The label is zoomable, that is, it scales according to the zoom factor. The label text is taken from the SDM model property name. The labelPosition parameter specifies that the label must be placed to the left of the node, and the labelSpacing parameter indicates that the maximum distance of the label from the node is 2 units.
In order to specify further layout parameters of the label, use the pseudoclass labelLayout:
 
node:labelLayout {
    ... any option of the IlvAnnealingPointLabelDescriptor...
}
In particular, you can specify whether the layout should treat or ignore the label:
 
node:labelLayout {
    treatAs: "IGNORED";
}
The treatAs parameter can take the following values:
*LABEL - the label is positioned by the label layout.
*OBSTACLE - the label is not moved by the label layout, but it occupies space that cannot be used by other labels
*IGNORED - the label is ignored even though the node that owns the label is not ignored.
Labels at links
Each instance of IlvGeneralLink has at most one label. This label can be placed by a hard-coded mechanism of IlvGeneralLink which does not take into account the free space, or it can be placed by the label layout renderer. If the label layout renderer is enabled, the label is always placed by the label layout.
The general link can have an arbitrary set of decorations. The label is usually the first of these decorations—that is, the decoration with index 0. Any decoration that implements the interface IlvLabelInterface can be used as a label. If no such decoration is specified, it is automatically generated if a label is required.
See the following sample specification of a link with a label:
 
link {
    class: "ilog.views.sdm.graphic.IlvGeneralLink";
    label: "@name";
}
The label text is taken from the SDM model property name. Since no decoration is specified, an instance of IlvZoomableLabel is automatically generated as the decoration with index 0. If you want to use a different class for the label, or if you want the label to have a specific graphic property such as a background color, you must specify the decoration explicitly:
 
link {
    class: "ilog.views.sdm.graphic.IlvGeneralLink";
    decorations[0]: "@+deco";
    label: "@name";
    decorationPositions[0]: "0.8";
}
Subobject#deco {
    class: "ilog.views.sdm.graphic.IlvGraphicFactories$ZoomableLabel";
    IlvRect: "0,0,5,5";
    backgroundOn: "true";
    background: "#BABABA";
}
The “ Subobject#deco ” rule specifies the graphic properties of the label. This label has a special background color. The declaration “ decorationPositions[0] ” specifies where the label attaches the link. If the label layout renderer is disabled, the label is placed in a hard-coded way at this position. If the label layout renderer is enabled, the label is placed approximately at this position, but also tries to avoid overlaps with other labels or obstacles.
General links may have many decorations, but the label layout recognizes only the first decoration of type IlvLabelInterface as a label, recognizes the general link itself as an obstacle, and ignores all other decorations of the general link.
In order to specify specific label parameters for the label layout, use the pseudo class “ labelLayout ”:
 
link:labelLayout {
    ... any option of the IlvAnnealingPolylineLabelDescriptor...
}
In particular, you can specify whether the layout should treat or ignore the label:
 
link:labelLayout {
    treatAs: "IGNORED";
}
The treatAs parameter can take the values LABEL, OBSTACLE, or IGNORED, as explained in Labels at nodes.
Labels at composite nodes
If you need nodes and links that can have multiple labels, you must use the classes IlvSDMCompositeNode and IlvSDMCompositeLink. Composite nodes and links can have any number of decorations (known as children). The label layout recognizes all children of type IlvLabel, IlvZoomableLabel or IlvText as labels, and all other children as obstacles.
The following example shows how to specify labels at composite nodes:
 
node {
    class: "ilog.views.sdm.graphic.IlvSDMCompositeNode";
    children[0]: "@+base";
    children[1]: "@+label1";
    children[2]: "@+label2";
 
    constraints[1]:@+attachmentLabel;
    constraints[2]:@+attachmentLabel;
}
 
#base {
   class:"ilog.views.graphic.IlvRectangle(definitionRect)";
   definitionRect:"@|rect(0,0,60,60)";
 
}
 
Subobject#label1 {
   class:"ilog.views.graphic.IlvText";
   label:@name;
 
}
 
Subobject#label2 {
   class:"ilog.views.graphic.IlvText";
   label:"hello";
 
}
 
Subobject#attachmentLabel {
   class:"ilog.views.graphic.composite.layout.IlvAttachmentConstraint";
   hotSpot:TopCenter;
   anchor:BottomCenter;
   offset: "0,3";
}
The composite node has three children: The first child (index 0, rule #base ) is the basic shape of the node. The other two children (index 1 and 2, rules Subobject#label1 and Subobject#label2 ) are the labels of the node. The first node label label1 uses the SDM model property name as text while label2 uses the constant string “ Hello ”. Composite nodes and links require children to be attached by attachment constraints. See Building composite nodes in CSS in JViews Diagrammer SDK.
The label layout treats the basic shape as an obstacle, and children with index 1 and 2 as labels. In order to specify label parameters for the label layout, use the pseudoclasses “ labelLayout ” and “ labelLayout_ i” where i is the child index of the corresponding label. This declaration applies to all labels of the node:
 
node:labelLayout {
    ... any option of the IlvAnnealingPointLabelDescriptor...
}
This declaration applies to the label with child index 2 of node.
 
node:labelLayout_2 {
    ... any option of the IlvAnnealingPointLabelDescriptor...
}
In particular, you can specify whether layout should treat or ignore the label:
 
node:labelLayout_2 {
    treatAs: "IGNORED";
}
The treatAs parameter can take the values LABEL, OBSTACLE and, or IGNORED, as explained in section Labels at nodes.
Labels at composite links
Setting labels on composite links is very similar to setting labels on composite nodes (see Labels at composite nodes, except that the values of the hotSpot and anchor parameters of the Subobject#attachmentLabel rule are different, as shown in the following example.
 
link {
      class: "ilog.views.sdm.graphic.IlvSDMCompositeLink";
      children[0]: "@+label1";
      children[1]: "@+label2";
      constraints[0]: "@+attachmentLabel";
      constraints[1]: "@+attachmentLabel";
}
#base {
   class:"ilog.views.graphic.IlvRectangle(definitionRect)";
   definitionRect:"@|rect(0,0,60,60)";
 
}
 
Subobject#label1 {
   class:"ilog.views.graphic.IlvText";
   label:@name;
 
}
 
Subobject#label2 {
   class:"ilog.views.graphic.IlvText";
   label:"hello";
 
}
 
Subobject#attachmentLabel {
   class:"ilog.views.graphic.composite.layout.IlvAttachmentConstraint";
hotSpot: "FromLink";
anchor: "Center";
       offset: "0,0";
}
Ignoring nodes or links
The following CSS sample shows how to ignore a node and all its labels. This means that the label layout algorithm does not treat the node as an obstacle and does not try to place its labels. The label layout algorithm behaves as if the object did not exist:
 
#node23 {
    LabelLayoutIgnored: "true";
}
Similarly, you can specify LabelLayoutIgnored for link in order to ignore the link and all its labels.
NOTE The CSS syntax is case-sensitive: LabelLayoutIgnored starts with an uppercase letter, while most other label layout declarations start with a lowercase letter.
Labels and obstacles in Java
The diagram component works with a predefined, complex labeling model that recognizes labels at instances of IlvGeneralNode, IlvSDMCompositeNode, IlvGeneralLink and IlvSDMCompositeLink. If you use other classes or if you want to place labels at other objects, you cannot use the diagram component and you have to code the labeling model.
The IlvLabelingModel class defines a suitable, generic API to position labels automatically through a Rogue Wave  JViews Diagrammer label layout algorithm. Its purpose is similar to IlvGraphModel for the graph layout framework.
The class IlvLabelingModel is an abstract base class that allows you to implement an adapter to your own data structures for the labeling algorithm (see Defining your own labeling model). To get the labeling model of an attached layout, use the method:
 
layout.getLabelingModel();
If labels and obstacles are contained in an IlvManager instance, you do not need to implement an adapter. You can use the default labeling model (the class IlvDefaultLabelingModel).
The default labeling model is suitable when the labels are upright rectangular objects and the overlap calculation considers their bounding boxes.
It is also suitable for rectangular labels that have a rotation that depends on the position of a label. For example, the label on a polyline link may be rotated to align the label with the gradient of the line segment of a link. The overlap calculation considers the rotated rectangle of the label in this case.
Rotation of rectangular labels (rotation dependent on the position of the labels)
The default labeling model may not be suitable when the labels have a nonrectangular shape that leaves large parts of the bounding box of the label empty. The overlap detection will wrongly assume that the empty space inside the bounding box causes overlaps
NOTE The default labeling model is not suitable for IlvGeneralNode, IlvGeneralLink, IlvSDMCompositeNode, IlvSDMCompositeLink, because these classes implement labels that are not directly contained in a manager. Therefore the diagram component uses a specialized labeling model.
The default labeling model considers subclasses of IlvLabel, IlvZoomableLabel and IlvText as labels and all other objects as obstacles. This is the most common case. However, you can redefine this meaning:
*If you want a graphic to be handled as a label even though it is not a subclass of IlvLabel or IlvZoomableLabel, call:
 
defaultLabelingModel.setLabel(graphic, true);
*If you do not want to handle an instance of IlvLabel, IlvZoomableLabel or IlvText as a label but as an immovable obstacle, call:
 
defaultLabelingModel.setObstacle(graphic, true);
*If you want a graphic to be ignored by the labeling model, call:
 
defaultLabelingModel.setLabel(graphic, false);
defaultLabelingModel.setObstacle(graphic, false);
This is useful particularly if you want to create graphics that act as background images and labels should be placed on top of the background images. If the background images were obstacles, the label layout algorithm would try to avoid the area covered by the background images.
The overlap calculation of the default labeling model takes the bounding box of the obstacles into account. This is a good approximation for the most objects. For subclasses of IlvLine, IlvPolyline, and IlvLinkImage, it takes the precise polyline shape into account. However, the default labeling model does not work well with spline obstacles.

Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.