For experts: special options of short link layout

Self-link style

Self-links are links whose origin and destination are the same node. The Short Link Layout provides two optional shapes for self-links.

Self-link style options

Example of setting the style of the self-links (Link Layout algorithm)

To set the style of the self-links:

In CSS

Add to the LinkLayout section:

layoutMode : "SHORT_LINKS";
globalSelfLinkStyle : "TWO_BENDS_ORTHOGONAL_STYLE";

In Java

Call layout.getShortLinkLayout(). setGlobalSelfLinkStyle

The valid values for style are:

IlvShortLinkLayout.TWO_BENDS_ORTHOGONAL_STYLE
IlvShortLinkLayout.THREE_BENDS_ORTHOGONAL_STYLE

Number of optimization iterations

The link shape optimization is stopped if the time exceeds the allowed time; see Allowed time (LL)), or if the number of iterations exceeds the allowed number of iterations.

Example of specifying the number of optimization iterations (Link Layout algorithm)

To set the allowed number of iterations to 3:

In CSS

Add to the LinkLayout section:

layoutMode : "SHORT_LINKS";
allowedNumberOfIterations : "3";

In Java

Call:

layout.getShortLinkLayout().setAllowedNumberOfIterations(3);

Note

You might want to disable the link shape optimization by setting the number of iterations to zero to increase the speed of the layout process.

Evenly spaced pins margin ratio

The margin ratio allows you to customize the way connection points are computed when the connector style (see Connector style) is EVENLY_SPACED_PINS , and when the AUTOMATIC_STYLE places the connection points using the EVENLY_SPACED_PINS style. This option has no effect if the connector style FIXED_OFFSET_PINS is used.

In the “evenly spaced pins” connector style, the connection points of the links are evenly spaced along the node border, preserving a margin to each extremity of the node border. The size of this margin is controlled by the margin ratio and is computed by multiplying the offset between the links by the ratio.

Example of specifying the margin ratio (Link Layout algorithm)

To specify this option:

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
evenlySpacedMarginRatio: "0.2";

In Java

Call layout.getShortLinkLayout(). setEvenlySpacedPinsMarginRatio

The input value must be a positive or zero value. The default value is 0.5 . Evenly Spaced Pins Margin Ratio shows examples of values with their meaning.

Evenly Spaced Pins Margin Ratio

Ratio value	Meaning
0	No margin.
0.5 (default value)	The margin is equal to half the offset between the links.
1	The margin is equal to the offset between the links.
2	The margin is equal to twice the offset between the links.

Link overlap nodes forbidden

With this option you can request the layout algorithm to avoid strictly reshaping links, such that they overlap some nodes. If overlaps are not forbidden, the algorithm tries to avoid overlaps anyway, but can create overlaps, for example, for the link to cross other links.

Note

Forbidding overlaps can slow down the layout and can increase the number of bends for those links that would overlap nodes if overlaps were not strictly forbidden.

Example of specifying link overlap nodes forbidden (Link Layout algorithm)

To specify this option:

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
linkOverlapNodesForbidden: "true";

In Java

Call

layout.getShortLinkLayout(). setLinkOverlapNodesForbidden

The default value of this option is false .

When overlaps are forbidden, the Short Link Layout algorithm uses the Long Link Layout as an auxiliary algorithm for laying out only the links that would otherwise overlap nodes.

Example of specifying Long Link Layout when overlaps forbidden (Link Layout algorithm)

To retrieve the auxiliary instance of Long Link Layout:

In CSS

It is not possible to access the auxiliary Long Link Layout, nor to tailor this auxiliary Long Link Layout.

In Java

Call this method on the IlvShortLinkLayout instance:

IlvLongLinkLayout getAuxiliaryLongLinkLayout()

This method allows you to get this auxiliary layout instance and to customize its parameters if needed. Notice that you must not modify the origin and destination point mode, nor disable the preservation of fixed links. Notice also that an IlvGraphModel instance is attached to the IlvLongLinkLayout instance only if needed, therefore the method getAuxiliaryLongLinkLayout().getGraphModel() can return null .

Incremental link reshape mode

In incremental mode, it is possible to customize the rules used by Short Link Layout to determine which links must keep their current shape as much as possible, as computed by the previous layout execution. With incremental link reshape mode, you can customize these rules separately for two categories of links.

See the methods:

IlvShortLinkLayout.getLinkConnectionBoxInterface()

and

IlvShortLinkLayout.getNodeBoxInterface()

The “modified links”: links that have either a different “link connection box” or are connected to nodes that have a different bounding box as during the previous layout execution.
The “unmodified links”: links that have the same “link connection box” and are connected to nodes that have the same bounding box as during the previous layout execution.

The mode can be customized either for both or for only one of these categories of links.

The incremental link reshape mode has no effect if incremental mode is disabled.

The layout algorithm provides two incremental link reshape modes. You can set the mode globally, in which case all the links have the same mode, or locally on each link, in which case different modes occur in the same drawing.

Global incremental link reshape mode

Example of specifying a global incremental link reshape mode (Link Layout algorithm)

To specify the global incremental link reshape mode:

In CSS

Add, for instance, these statements to the LinkLayout section:

globalIncrementalModifiedLinkReshapeMode: "FIXED_NODE_SIDES_MODE";
globalIncrementalUnmodifiedLinkReshapeMode: "FIXED_SHAPE_TYPE_MODE";

In Java

Use the following methods:

layout.getShortLinkLayout(). setGlobalIncrementalModifiedLinkReshapeMode

layout.getShortLinkLayout(). setGlobalIncrementalUnmodifiedLinkReshapeMode

The valid values for mode are:

IlvShortLinkLayout.FIXED_SHAPE_TYPE_MODE (the default)

The incremental layout preserves the shape type of the link. This means that both the number of bends and the node sides to which the link is connected are preserved.
IlvShortLinkLayout.FIXED_NODE_SIDES_MODE

The incremental layout preserves the node sides to which the links are connected.
IlvShortLinkLayout.FIXED_CONNECTION_POINTS_MODE

The incremental layout preserves the connection points of the links.
IlvShortLinkLayout.FIXED_MODE

The links are not reshaped at all during incremental layout. Only newly added links are rerouted.
IlvShortLinkLayout.FREE_MODE

The incremental layout is allowed to freely reshape the links. It is equivalent to a non-incremental behavior for all the links, hence it is recommended to disable the incremental mode instead of using FREE_MODE as global incremental reshape mode.

Of course, the settings that may have been done by “fixing” links (see Preserve fixed links (LL)) or by customizing the origin or destination point mode (see End points mode (LL)) are still respected.
IlvShortLinkLayout.MIXED_MODE

Each link can have a different mode.

In CSS, you can omit the prefix IlvShortLinkLayout when specifying the value of the mode.

Individual incremental link reshape mode

All links have the same incremental link reshape mode unless the global incremental link reshape mode is IlvShortLinkLayout.MIXED_MODE .

Only when the global mode is set to MIXED_MODE can each link have an individual mode.

Example of specifying an individual incremental link reshape mode (Link Layout algorithm)

To specify the mode of an individual link:

In CSS

Write a rule that selects the link, for instance:

LinkLayout {
  layoutMode: "SHORT_LINKS";
  globalIncrementalModifiedLinkReshapeMode: "MIXED_MODE";
  globalIncrementalUnmodifiedLinkReshapeMode: "MIXED_MODE";
}
#link1{
  IncrementalModifiedLinkReshapeMode: "FIXED_NODE_SIDES_MODE";
  IncrementalUnmodifiedLinkReshapeMode: "FIXED_SHAPE_TYPE_MODE";
}

In Java

Use the following methods on the IlvShortLinkLayout instance:

void setIncrementalModifiedLinkReshapeMode(Object link, int mode);

void setIncrementalUnmodifiedLinkReshapeMode(Object link, int mode);

int getIncrementalModifiedLinkReshapeMode(Object link);

int getIncrementalUnmodifiedLinkReshapeMode(Object link);

The valid values for mode are:

IlvShortLinkLayout.FIXED_SHAPE_TYPE_MODE (the default)
IlvShortLinkLayout.FIXED_NODE_SIDES_MODE
IlvShortLinkLayout.FIXED_CONNECTION_POINTS_MODE
IlvShortLinkLayout.FREE_MODE
IlvShortLinkLayout.FIXED_MODE

Same shape for multiple links

You can force the layout algorithm to compute the same shape for all the links that have common origin and destination nodes. The links have parallel shapes.

When this option is disabled, the layout is free to compute different shapes for links connecting the same pair of nodes. Generally, different shapes are chosen to avoid some overlaps.

Two interconnected
nodes first with the same-shape option disabled and then with the
same-shape option enabled

Same shape for multiple links option

Example of specifying the same shape for multiple links (Link Layout algorithm)

To enable the same shape for multiple links:

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
sameShapeForMultipleLinks : "true";

In Java

Use the method:

layout.getShortLinkLayout().setSameShapeForMultipleLinks(true);

The default value is false .

Link crossing penalty

The computation of the shape of the links is driven by the objective to minimize a cost function, which is proportional to the number of link-to-link crossings and link-to-node crossings. By default, these two types of crossing have equal weights of 1 . You can increase the weight of the link-to-node crossings.

Example of specifying link-to-node crossing penalty (Link Layout algorithm)

To increase the weight of the link-to-node crossings:

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
linkToNodeCrossingPenalty  : "5.0";

In Java

Use the method:

layout.getShortLinkLayout().setLinkToNodeCrossingPenalty(5.f);

This setting increases the possibility of obtaining a layout with no link-to-node crossings (or with only a few crossings), at the expense of the possibility that more link-to-link crossings could occur.

Alternatively, you can increase the weight of the link-to-link crossings.

Example of specifying link-to-link crossing penalty (Link Layout algorithm)

To increase the weight of the link-to-link crossings, for instance, to a value of 3 :

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
linkToLinkCrossingPenalty  : "3.0";

In Java

Use the method:

layout.getShortLinkLayout().setLinkToLinkCrossingPenalty(3.f);

This setting increases the possibility of obtaining a layout with no link-to-link crossings (or with only a few crossings), at the expense of the possibility of more link-to-node crossings.

Bypass distance

If the origin and destination nodes are too close, there might not be enough space for routing the link directly between the end nodes. Therefore, by default, if the end nodes are closer than a threshold distance, the layout chooses link shapes that bypass the interval between close nodes. (See End nodes and bypass distance.)

End nodes and bypass distance

The bypass distance is the minimum distance between the origin and destination nodes for which a link shape going directly from one node to another is allowed. The algorithm tries to avoid link shapes that connect directly the sides of the end nodes that are closer than the bypass value.

Example of specifying the bypass distance (Link Layout algorithm)

To set the bypass distance:

In CSS

Add to the LinkLayout section:

layoutMode: "SHORT_LINKS";
bypassDistance  : "3.0";

In Java

Call

void setBypassDistance(float dist)

The default value is a strictly negative value. If the bypass distance is strictly negative, the value of the minimum final segment length parameter is used as the bypass distance. See Minimum final segment length. It allows the automatic adjustment of the bypass distance according to the current value of the minimum final segment length. This behavior is suitable in most cases. You can specify a nonnegative value to override the default behavior.

Using a link connection box interface

By default, the connection points of the links are distributed on the border of the bounding box of the nodes symmetrically with respect to the middle of each side. Sometimes, it might be necessary to place the connection points on a rectangle smaller or larger than the bounding box, possibly in an asymmetric way. For example, when labels are displayed below or above nodes.

Example of using a link connection box interface to modify the position of the connection points (Link Layout algorithm)

You can modify the position of the connection points of the links by implementing a class that implements the IlvLinkConnectionBoxInterface interface.

In CSS

It is not possible to set the link connection box interface.

In Java

This interface defines the following method:

public IlvRect getBox(IlvGraphModel graphModel, Object node);

This method allows you to return the effective rectangle on which the connection points of the links are placed.

A second method defined on the interface allows the connection points to be “shifted” tangentially, in a different way for each side of each node:

public float getTangentialOffset(IlvGraphModel graphModel, Object node, int 
nodeSide);

For instance, to set a link connection box interface that returns a link connection rectangle that is smaller than the bounding box for all nodes of type MyNodeEditPart and shifts up the connection points on the left and right side of all the nodes, call:

layout.setLinkConnectionBoxInterface(new IlvLinkConnectionBoxInterface() {
    public IlvRect getBox(IlvGraphModel graphModel, Object node) {
        IlvRect rect = graphModel.boundingBox(node);
        if (node instanceof MyNodeEditPart) {
            // for example, the size of the bounding box is reduced by 4 units 
            rect.resize(rect.width-4.f, rect.height-4.f); 
        }
        return rect;
    }
    public float getTangentialOffset(IlvGraphModel graphModel, 
                                     Object node, int nodeSide) {
        switch (nodeSide) {
          case IlvDirection.Left:
          case IlvDirection.Right:
            return -10; // shift up with 10 for both left and right side
          case IlvDirection.Top:
          case IlvDirection.Bottom:
          default:
            return 0; // no shift for top and bottom side
        }
    }
});

Self-link style options shows the effects of customizing the connection box. On the left is the result using the default settings: the connection points are distributed on the bounding box of the node (which includes the label) and are symmetric with the middle of each node side (including the label). On the right is the result after specifying a link connection box interface. On the lower side of the nodes, the links are now connected to the node (passing over the label), while on the left and right sides of the nodes, the connection points are now symmetric to the middle of the node (without the label).

A graph
with the default link connection box and then a customized link connection
box

Customization of the link connection box