For experts: special options of short link layout

The following options are for ibm_ilog.graphlayout.shortlink.ShortLinkLayout only.

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.
Graph
showing first the two-bend self-link style and then the three-bend
self-link style
Self-link style options
Example of setting the style of the self-links (Link Layout algorithm)
To set the style of the self-links:
Use the method setGlobalSelfLinkStyle:
layout.setGlobalSelfLinkStyle(ibm_ilog.graphlayout.shortlink.ShortLinkLayout.TWO_BEND_ORTHOGONAL_STYLE);
The valid values for style are:
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.TWO_BENDS_ORTHOGONAL_STYLE
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.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:
layout.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:
layout.setEvenlySpacedPinsMarginRatio(1);
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:
layout.setLinkOverlapNodesForbidden(true);
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:
Call the following method on the ibm_ilog.graphlayout.shortlink.ShortLinkLayout instance:
var longLinkLayout = layout.getAuxiliaryLongLinkLayout();
This method allows you to get this auxiliary layout instance and to customize its parameters if needed. You must not modify the origin and destination point mode, nor disable the preservation of fixed links.

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.
  • 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:
layout.setGlobalIncrementalModifiedLinkReshapeMode(ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_NODE_SIDES_MODE);
The valid values for mode are:
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.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.
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_NODE_SIDES_MODE
    The incremental layout preserves the node sides to which the links are connected.
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_CONNECTION_POINTS_MODE
    The incremental layout preserves the connection points of the links.
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_MODE
    The links are not reshaped at all during incremental layout. Only newly added links are rerouted.
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FREE_MODE
    The incremental layout is allowed to freely reshape the links. It is equivalent to non-incremental behavior for all the links; hence it is recommended to disable incremental mode instead of using FREE_MODE as global incremental reshape mode.
    The settings that may have been performed by “fixing” links (see Preserve fixed links (LL)) or by customizing the origin or destination point mode (see End points mode (LL)) are still kept.
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.MIXED_MODE
    Each link can have a different mode.

Individual incremental link reshape mode

All links have the same incremental link reshape mode unless the global incremental link reshape mode is ibm_ilog.graphlayout.shortlink.ShortLinkLayout.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:
Use the following methods on the ibm_ilog.graphlayout.shortlink.ShortLinkLayout instance:
layout.setIncrementalModifiedLinkReshapeMode(link, mode);  
layout.setIncrementalUnmodifiedLinkReshapeMode(link, mode);
var mode = layout.getIncrementalModifiedLinkReshapeMode(link);
var mode = layout.getIncrementalUnmodifiedLinkReshapeMode(link); 
The valid values for mode are:
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_SHAPE_TYPE_MODE (the default)
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_NODE_SIDES_MODE
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FIXED_CONNECTION_POINTS_MODE
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.FREE_MODE
  • ibm_ilog.graphlayout.shortlink.ShortLinkLayout.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:
Use the method:
layout.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:
Use the method:
layout.setLinkToNodeCrossingPenalty(5);
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:
Use the method:
layout.setLinkToLinkCrossingPenalty(3);
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.)
Two interconnected
nodes first more distant than the bypass distance and then closer
than the 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:
Use the method setBypassDistance.
layout.setBypassDistance(1);
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 ILinkConnectionBoxProvider interface.
This interface defines the following method:
getBox(graphModel, node)
With this method, you can obtain 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:
getTangentialOffset(graphModel, node, nodeSide)
For example, to set a link connection box provider that returns a link connection rectangle that is smaller than the bounding box for all nodes of type MyNode and that shifts up the connection points on the left and right side of all the nodes, call:
dojo.declare('MyLinkConnectionBoxProvider', ibm_ilog.graphlayout.ILinkConnectionBoxProvider,
 {
    getBox: function(graphModel, node)
   {
        var rect:Rectangle = graphModel.getBounds(node);
        if (node is MyNode) {
            // for example, the size of the bounding box is reduced:
            rect.x += 4;
            rect.y += 4;
            rect.width -= 8;
            rect.height -= 8;
        }
        return rect;
    },

    getTangentialOffset: function(graphModel, node, side)
    {
        switch (side) {
             case ibm_ilog.graphlayout.Direction.LEFT:
             case ibm_ilog.graphlayout.Direction.RIGHT:
                 return -10; // shift up with 10 for both left and right side
             case ibm_ilog.graphlayout.Direction.TOP:
             case ibm_ilog.graphlayout.Direction.BOTTOM:
             default:
                 return 0; // no shift for top and bottom side
         }
    }
});

layout.setLinkConnectionBoxProvider(new MyLinkConnectionBoxProvider());
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