Labels and obstacles in a diagram component

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.