Specific parameters for both short and long link layouts

Layout mode (LL)

The Link Layout algorithm has two layout modes.

To select a layout mode:

In CSS

Add to the LinkLayout section:

layoutMode : "SHORT_LINKS";

In Java™

Use the method:

void setLayoutMode(int mode);

The valid values for mode are:

IlvLinkLayout.SHORT_LINKS (the default)
IlvLinkLayout.LONG_LINKS

The figure Short and long link modes with orthogonal links shows a small sample graph in short and long link modes. The short link mode bundles the links well. Due to the bundling, some red links appear to be unconnected to the green nodes. The algorithm cannot find a route for the long red links without overlapping some nodes or without overlapping the green link. The long link mode works on a grid. It is specialized for long links and avoids overlapping any nodes or link segments. It can connect to the green nodes by choosing connection points on different sides of the end nodes. This advantage, however, is paid for by a less regular structure that does not bundle the links and a larger number of link crossings.

Picture
of link layouts illustrating the short link layout mode and the long
link layout mode

Short and long link modes with orthogonal links

Choosing the appropriate layout (LL)

The short link mode must be used if any of the following conditions apply:

Most links are short and it is not fatal if long links overlap obstacles.
The link routes must be placed freely and cannot be restricted to a grid.
It is important to limit the number of bends.

The long link mode must be used if any of the following conditions apply:

Many links are long and it is important that long links do not overlap obstacles.
There is a preferred routing because the nodes are already placed on the grid.
It is important to have a guaranteed minimum distance between link segments.
An increasing number of bends is acceptable if it avoids any overlapping.

Labyrinth routing with long link layout shows how the long link mode can be used to find an orthogonal route without any overlapping in a labyrinth of node obstacles.

A graph
showing long link mode used to find an orthogonal route without any
overlapping in a labyrinth of node obstacles

Labyrinth routing with long link layout

Link style (LL)

The layout algorithms provide two link styles. You can set the link style globally, in which case all links have the same shape, or locally on each link, in which case different link shapes occur in the same drawing.

Note

The layout algorithm may raise an IlvInappropriateLinkException if layout is performed on an IlvGrapher, but inappropriate link classes or link connector classes are used. See Layout exceptions for details and solutions to this problem.

Global link style

Example of setting global link style (Link Layout algorithms)

To set the global link style:

In CSS

Add to the LinkLayout section:

globalLinkStyle: "ORTHOGONAL_STYLE";

In Java

Use the method:

void setGlobalLinkStyle(int style);

The valid values for style are:

IlvLinkLayout.ORTHOGONAL_STYLE (the default)

The links are reshaped in an orthogonal form (alternating horizontal and vertical segments). See Short link layout with orthogonal links and Long link layout with orthogonal links as examples.
IlvLinkLayout.DIRECT_STYLE

The links are reshaped to a polygonal line composed of three segments: a straight-line segment that starts and ends with a small horizontal or vertical segment. See The same graph in short link layout with direct links as an example.
IlvLinkLayout.MIXED_STYLE

Each link can have a different link style. The style of each individual link can be set to have different link shapes occurring on the same graph.

Individual link style

All links have the same style of shape unless the global link style is IlvLinkLayout.MIXED_STYLE .

Only when the global link style is set to MIXED_STYLE can each link have an individual link style.

A graph
laid out in short link mode with different link styles

Different link styles mixed in the same drawing (short link layout)

A graph
laid out in long link mode with different link styles

Different link styles mixed in the same drawing (long link layout)

Example of specifying individual link style (Link Layout algorithms)

To set and retrieve the style of an individual link:

In CSS

First set the global link style to MIXED_STYLE, then write a rule to select the link:

LinkLayout {
   globalLinkStyle : "MIXED_STYLE";
}
#link1 {
  LinkStyle: "DIRECT_STYLE ";
}

In Java

Use the methods:

void setLinkStyle(Object link, int style);

int getLinkStyle(Object link);

The valid values for style are:

IlvLinkLayout.ORTHOGONAL_STYLE (the default)
IlvLinkLayout.DIRECT_STYLE
IlvLinkLayout.NO_RESHAPE_STYLE (that is, the link is not reshaped in any way)

Note

The link style of a Link Layout graph requires links in an IlvGrapher that can be reshaped. Links of type IlvLinkImage, IlvOneLinkImage, IlvDoubleLinkImage, IlvOneSplineLinkImage, and IlvDoubleSplineLinkImage cannot be reshaped. You should use the class IlvPolylineLinkImage or IlvSplineLinkImage instead

End points mode (LL)

Normally, the layout algorithm is free to choose the termination points of each link. However, if fixed-link connectors are used (for instance, IlvPinLinkConnector), the user can specify that the current fixed termination pin of a link must be used.

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

Global end point mode

Example of specifying global end point mode (Link Layout algorithm)

To set the global end point mode:

In CSS

Add to the LinkLayout section:

globalOriginPointMode : "FIXED_MODE";
globalDestinationPointMode : "FIXED_MODE";

In Java

void setGlobalOriginPointMode(int mode);

void setGlobalDestinationPointMode(int mode);

The valid values for mode are:

IlvLinkLayout.FREE_MODE (the default)

The layout is free to choose the appropriate position of the connection point on the origin or destination node.
IlvLinkLayout.FIXED_MODE

The layout must keep the current position of the connection point on the origin or destination node.
IlvLinkLayout.MIXED_MODE

Each link can have a different end point mode.

The connection points are automatically considered as fixed if they are connected to grapher pins.

Individual end point mode

All links have the same end point mode unless the global end point mode is IlvLinkLayout.MIXED_MODE .

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

Example of specifying individual end point mode (Link Layout algorithm)

To set the mode of an individual link:

In CSS

First set the global origin and destination point mode to MIXED_MODE, then write a rule that selects the link:

LinkLayout {
   globalOriginPointMode      : "MIXED_MODE";
   globalDestinationPointMode : "MIXED_MODE";
}
#link1{
  OriginPointMode      : "FREE_MODE";
  DestinationPointMode : "FREE_MODE";
}

In Java

Use the methods:

void setOriginPointMode(Object link, int mode);

int getOriginPointMode(Object link);

void setDestinationPointMode(Object link, int mode);

int getDestinationPointMode(Object link);

The valid values for mode are:

IlvLinkLayout.FREE_MODE (the default)
IlvLinkLayout.FIXED_MODE

The connection points are automatically considered as fixed if they are connected to grapher pins.

Note

The layout algorithm may raise an IlvInappropriateLinkException if layout is performed on an IlvGrapher, but inappropriate link classes or link connector classes are used. See Layout exceptions for details and solutions to this problem.

Incremental mode (LL)

The Link Layout algorithm normally routes all links from scratch. If the graph changes incrementally because you add or remove links or nodes, the subsequent layout can differ considerably from the previous layout. To avoid this effect and to help the user to retain a mental map of the graph, the algorithm has an incremental mode.

Example of enabling incremental mode (Link Layout algorithm)

To enable the incremental mode:

In CSS

Add to the LinkLayout section:

incrementalMode : "true";

In Java

Call:

layout.setIncrementalMode(true);

In incremental mode, the layout tries to minimize the changes to the layout. A link is only rerouted if it is new, if a link bend has moved, if its layout parameters have changed, or if a node was moved such that it overlaps the link.

In short link mode, if the next layout is incremental, the links preserve the connection side and the general shape calculated by a previous layout, except if one of their end nodes has been moved or resized.

In long link mode, a new route is sought for the links that are no longer on the grid or that overlap with nodes. The shape and the connection side of the rerouted links can change completely. Links that are already on the grid and do not overlap nodes or other links are not rerouted in incremental mode. It is also possible to specify which link must be rerouted by the next incremental layout even though the layout has not changed.

Example of specifying which link must be rerouted by the next incremental layout (Link Layout algorithm)

To select an individual link to be used for incremental rerouting:

In CSS

Write a rule to select the link:

#link1 {
  MarkForIncremental: "true";
}

In Java

Use the method:

void markForIncremental(Object link);

Intergraph link routing (LL)

A nested graph is a graph with nodes that are subgraphs. In a nested graph, normal links and intergraph links can occur (see Nested managers and nested graphers in Advanced Features of JViews Framework). Normally, both end nodes of a link belong to the same subgraph. Intergraph links are those links whose end nodes belong to different subgraphs. Intergraph links belong to the lowest common grapher in the nesting structure that contains both end nodes. The following figure shows a nested graph with blue normal links and red intergraph links.

Nested graph with normal links (blue) and intergraph links (red)

By default, Link Layout routes both the normal links and the intergraph links.

Example of routing only normal links (Link Layout algorithm)

To route only normal links, disable intergraph link routing:

In CSS

Add to the LinkLayout section:

interGraphLinksMode : "false" ;

In Java

Call:

layout.setInterGraphLinksMode(false);

Example of routing intergraph or normal links or both (Link Layout algorithm)

If the intergraph links mode is enabled, you can select whether only the intergraph links are routed or whether the intergraph links and the normal links are routed at the same time.

In CSS

If you set:

combinedInterGraphLinksMode : "false";

the next layout routes the intergraph links but does not reshape any normal links.

If you set:

combinedInterGraphLinksMode : "true"

the next layout routes both the normal links and the intergraph links.

In Java

If you call:

layout.setCombinedInterGraphLinksMode(false);

the next layout routes the intergraph links but does not reshape any normal links. If you call:

layout.setCombinedInterGraphLinksMode(true);

the next layout routes both the normal links and the intergraph links.

When the intergraph links mode is enabled, the layout cannot route the links incrementally (see Incremental mode (LL)) and the layout animation is disabled (see Animation).

The layout routes only those links that belong to the attached graph. In a nested graph, each subgraph is attached to a different layout instance. Therefore, when starting a normal (nonrecursive) layout for the top-level graph (see Nested graph with normal links (blue) and intergraph links (red)), not all links are routed that are shown in this figure, but only those links that belong to the top-level graph.

In the following figure, the yellow shading indicates the subgraph to which the nonrecursive link layout is currently applied. The top-level graph is on the left and on the right is the subgraph, which is shaded yellow. If the intergraph links mode is enabled, both the red (intergraph) and blue (normal) links are routed. If the intergraph links mode is disabled, only the blue (normal) links are routed. The gray links are not routed because they do not belong to the graph to which the link layout is applied.

Picture
showing which links are routed in a nested graph

Links routed in a nested graph: top-level graph and then subgraph

To route all links of a nested graph, you need to apply the Link Layout recursively. Details of the recursive layout mechanism are explained in Recursive layout. For example:

layout.setInterGraphLinksMode(true);
layout.performLayout(force, redraw, true);

routes the intergraph links recursively in all subgraphs. If you use a layout provider (a class that implements the interface IlvLayoutProvider ), you need to set the intergraph links mode for all subgraphs explicitly:

IlvLayoutProvider layoutProvider = ...
// first, set the intergraph mode for all layouts
Enumeration e = graphModel.getLayouts(layoutProvider, true);
while (e.hasMoreElements()) {
    IlvGraphLayout layout = (IlvGraphLayout) e.nextElement();
    if (layout instanceof IlvLinkLayout)
        ((IlvLinkLayout) layout).setInterGraphLinksMode(true);
}
// then perform layout recursively using the provider
graphModel.performLayout(layoutProvider, force, redraw, true);

To perform the intergraph link routing recursively in combination with a layout that places the nodes or that arranges labels, use an instance of the class IlvMultipleLayout to encapsulate the Link Layout and the other layouts, and then perform the Multiple Layout recursively all at once. For details, see Recursive layout.