Explains what labels and obstacles are.

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:

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:

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:

In particular, you can specify whether the layout should treat or ignore the label:

The treatAs parameter can take the following values:

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:

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:

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 ”:

In particular, you can specify whether the layout should treat or ignore the label:

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:

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:

This declaration applies to the label with child index 2 of node.

In particular, you can specify whether layout should treat or ignore the label:

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.

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:

Similarly, you can specify LabelLayoutIgnored for link in order to ignore the link and all its labels.

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:

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.

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

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:

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.