Describes the support for generic features and parameters provided by each layout algorithm.

The generic features and parameters of graph layout described in Base class parameters and features allow you to customize the behavior of the layout algorithms to meet specific needs and to perform useful operations such as saving the layout parameters in a file.

The following table indicates the generic features and parameters that are supported by each layout algorithm. These parameters are defined in the base class for all layout algorithms, IlvGraphLayout.

 

1 Only if the sublayouts contained in the Multiple or Recursive layout support it.

The IlvGraphLayout class defines a number of generic features and parameters. These features and parameters can be used to customize the layout algorithms.

Although the IlvGraphLayout class defines the generic parameters, it does not control how they are used by its subclasses. Each layout algorithm (that is, each subclass of IlvGraphLayout ) supports a subset of the generic features and determines the way in which it uses the generic parameters. When you create your own layout algorithm by subclassing IlvGraphLayout, you decide whether you want to use the features and the way in which you are going to use them.

The IlvGraphLayout class defines the following generic features:

Support by algorithms of generic features and parameters provides a summary of the generic parameters supported by each layout algorithm. If you are using one of the subclasses provided with the graph layout API, check the documentation for that subclass to know whether it supports a specific parameter and how it interprets the parameter.

Allowed time

Several layout algorithms can be designed to stop computation when a user-defined time specification is exceeded. It can be done for different reasons: for security to avoid a long computation time on large graphs, or as an upper limit for algorithms that iteratively improve a current solution and have no other criteria to stop the computation.

To specify that the layout is allowed to run for 60 seconds:

Add to the GraphLayout section:

Call:

The time is in milliseconds. The default value is 32000 (32 seconds).

If you subclass IlvGraphLayout, use the following method to know whether the specified time was exceeded:

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Animation

Some iterative layout algorithms can optionally redraw the graph after each iteration or step. This may create a pleasant animation effect and may be used to keep the user aware of the evolution of the layout computation by showing intermediate results (as a kind of progress bar). However, this increases the duration of the layout because additional redrawing operations need to be performed.

To specify that the layout animation is enabled:

Add to the GraphLayout section:

Call:

Layout animation is disabled by default.

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Automatic layout

For some layout algorithms, it may be suitable to have the layout automatically performed again after each change of the graph, that is, when a node or link moves, is added, or is removed. Automatic layout is most useful for link layouts, in a situation where the shape of the links must remain optimal after each editing action of the end-user. It also works well with other layout algorithms that offer an incremental behavior, that is, for which a small change of the graph usually produces only a small change of the layout. Automatic layout is generally not suitable for non-incremental layout algorithms.

To enable automatic layout:

Add to the GraphLayout section:

Call:

The following hints are important when programming in Java on an IlvGrapher instance:

For more information about automatic layout, see the method performAutoLayout in the Java API Reference Documentation.

Coordinates mode

The geometry, that is, the position and size, of the graphic objects that are used to represent nodes and links in an IlvGrapher instance is subject to a transformer ( IlvTransformer). By default, the layout algorithms consider the geometry of the nodes and links of an IlvGrapher in a coordinate space that is appropriate for most cases. In some situations, it can be useful to specify a different coordinate space. For details, see Choosing the layout coordinate space.

To specify, for instance, the view coordinate space:

Add to the GraphLayout section:

Use the method:

The valid values for the coordinates mode are:

In CSS, you omit the prefix IlvGraphLayout when specifying the value of the coordinates mode (see Example of specifying coordinate space).

The default mode is INVERSE_VIEW_COORDINATES .

See also Specifying the mode for layout coordinates.

Layout of connected components

The base class IlvGraphLayout provides generic support for the layout of a disconnected graph (composed of connected components).

For details, see Laying out connected components of a disconnected graph.

To enable the placement of disconnected graphs:

Add to the GraphLayout section:

Call:

When enabled, a default instance of the class IlvGridLayout is used internally to place the disconnected graphs. If necessary, you can customize this layout.

To customize this layout:

Add to the GraphLayout section:

and add a new section for the definition of the layout used to place the disconnected graphs, including statements for the parameters you want, for instance:

Call:

The various capabilities of the class IlvGridLayout cover most of the likely needs for the placement of disconnected graphs. If necessary, you can write your own subclass of IlvGraphLayout to place disconnected graphs and specify it instead of IlvGridLayout :

Add to the GraphLayout section:

and add a new section to define the layout used to place disconnected graphs, including statements for the parameters you want, for instance:

Call:

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. You can write a subclass to override this behavior.

Layout region

Some layout algorithms can control the size of the graph drawing and can take into account a user-defined layout region.

To specify a region of 100 by 100:

If you work with style sheets, you can specify the layout region as a rectangle, for instance:

The above CSS statement sets the layout region to the rectangle with the top-left corner at coordinates 0,0 and width and height at 100.

Besides, the method

which defines the layout region in manager coordinates, there are two more ways to set the layout region. These ways are only available in Java, not in CSS:

To access the layout region, use the method:

This method returns a copy of the rectangle that defines the specified layout region. The dimensions of the rectangle are in the manager (grapher) coordinates. Depending on the last method you called, one of the following cases may occur:

The layout algorithms call a different method:

This method first tries to use the layout region specification by calling the method getSpecLayoutRegion. If this method returns a non-null rectangle, this rectangle is returned. Otherwise, the method tries to estimate an appropriate layout region according to the number and size of the nodes in the attached graph. If no graph is attached, or the attached graph is empty, it returns a default rectangle ( 0, 0, 1000, 1000 ).

To indicate whether a subclass of IlvGraphLayout supports the layout region mechanism, use the method:

The default implementation returns false. A subclass can override this method in order to return true to indicate that this mechanism is supported.

Link clipping

Some layout algorithms try to calculate the specific connection points of links at the border of nodes and require instances of IlvFreeLinkConnector attached to the nodes, while other layout algorithms do not calculate any connection points but simply let the link connectors (any subclass of IlvLinkConnector ) determine how the links connect to the nodes.

If a layout algorithm calculates specific connection points, then it places the connection points of links by default at the border of the bounding box of the nodes. If the node has a nonrectangular shape such as a triangle, rhombus, or circle, you may want to place the connection points exactly on the border of the shape. This can be achieved by code by specifying a link clip interface. The link clip interface allows you to correct the calculated connection point so that it lies on the border of the shape. Some examples are shown in the following figure.

To specify the link clip interface:

It is not possible to specify the link clip interface in CSS, however the sample in Writing a new layout renderer to clip links shows how to integrate a link clip interface into the graph layout renderer.

Use the method:

You modify the position of the connection points of the links by implementing a class that implements the IlvLinkClipInterface. This interface defines the following method:

This method getConnectionPoint allows you to return the corrected connection point when the layout algorithm tries to connect to the proposed connection point. The auxControlPoint parameter is the auxiliary control point of the link segment that ends at the proposed connection point. The flag origin indicates whether the connection point is the start point or the end point of the link.

One strategy is to calculate the intersection between the ray starting at auxControlPoint and going through proposedConnectionPoint and the shape of the node. If there is any intersection, we return the one closer to auxControlPoint. If there is no intersection, clipping is not possible and we return the proposed connection point.

The following sample shows how to set a link clip interface that clips the connection points at the border of an ellipse or circle node:

The sample in Writing a new layout renderer to clip links shows how to integrate a link clip interface into the graph layout renderer.

To indicate whether a subclass of IlvGraphLayout supports the link clip interface, use the method:

The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.

Link connection box

If a layout algorithm calculates specific connection points, it places the connection points of links by default at the border of the bounding box of the nodes symmetrically with respect to the middle of each side. Sometimes it can be necessary to place the connection points on a rectangle smaller or larger than the bounding box, possibly asymmetrically. For example, connection points can be placed asymmetrically when labels are displayed above or below nodes. See Effect of link connection box interface. It can be achieved by specifying a link connection box interface. The link connection box interface allows you to specify for each node a node box different from the bounding box that is used to connect the links to the node.

It is not possible to specify the link connection box interface in CSS. The diagram component uses some predefined link connection box interfaces in combination with nodes of type IlvGeneralNode. If you need to use a different link connection box interface, you must integrate it in the graph layout renderer in the same way as the link clipping interface (see Writing a new layout renderer to clip links for a sample that integrates the link clipping interface).

To set a link connection box interface in Java, call:

You implement the link connection box interface by defining a class that implements the IlvLinkConnectionBoxInterface. This interface defines the following method:

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:

How the interfaces are used and which connection points are the final result are specific to each layout algorithm.

Hierarchical Layout, Tree Layout, and Link Layout use the link connection box to define the box of the node where links should be attached.

The following figure shows the effects of customizing the connection box. On the left is the result without any link connection box interface. On the right is the result that shows the effect when the link connection box interface returns the dashed rectangle for the blue node.

Bus Layout, Circular Layout, Random Layout, Topological Mesh Layout, and Uniform Length Edges Layout do not spread out links at the node border, but can route links to point to the node center. See the method IlvBasicLinkStyleLayout.setConnectLinksToNodeCenters(boolean).

If a node has an irregular shape, the links should sometimes not point towards the center of the node bounding box, but to a virtual center inside the node. The link connection box interface can be used to define the virtual node center. The following figure shows an example of the effect.

If the links are clipped at the irregular green star node on the left of the figure, they will not point toward the center of the star, but toward the center of the bounding box of the node. You can correct this effect by specifying a link connection box interface that returns a smaller node box than the bounding box, such as shown on the right of the figure. Alternatively, the problem could be corrected by specifying a link connection box interface that returns the bounding box as the node box, but with additional tangential offsets that shift the virtual center of the node.

For example, 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 IlvShadowRectangle and shifts up the connection points on the left and right side of all the nodes, call:

To indicate whether a subclass of IlvGraphLayout supports the link connection box interface, use the method:

The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.

Spline routing

Some layout algorithms always use straight links, while other layout algorithms can calculate bend points for polyline links. If splines are used instead of polyline links, special control points must be calculated for spline links. There is a generic spline control point optimization available as a postprocessing step.

If a layout algorithm supports multiple link shapes, the spline optimization affects only those links with bends. It does not affect straight links or links that are marked as fixed or non-reshapeable. Furthermore, it affects only those links that are really spline links. If you use customized IlvGraphic data structures instead of IlvSplineLinkImage or IlvGeneralLink, you must set an IlvSplineLinkFilter which tells the layout which link classes are splines. By default, only IlvSplineLinkImage or IlvGeneralLink are recognized as splines.

If you work with style sheets, add to the GraphLayout section, for example:

See below the meaning of these parameters.

To enable the spline routing, call:

When the layout algorithm needs to create a bend, the spline routing tries to determine a triangle at the bend so that the curve of the spline runs inside this triangle. The size of the triangle depends on the available free space and the location of the other nodes, which are considered obstacles for the spline. The side length of the triangle is controlled by two parameters:

The algorithm tries to find a triangle with a side length between min and max. If a lot of free space is available, it chooses a triangle at max size. If no free space is available, it chooses a triangle at min size, even if this will cause an overlap of the spline with neighbor nodes. Therefore it is recommended to set the minimum spline curve size to a very small value.

The algorithm chooses isosceles triangles whenever possible, because the shape of a spline link looks more balanced if the curves run inside isosceles triangles. However, if there is no available space, then isosceles triangles are impossible and triangles with different side lengths are chosen. A threshold determines how small a triangle can be before nonisosceles triangles are chosen:

A spline link filter is a subclass of IlvSplineLinkFilter that determines which links are splines. The base class IlvSplineLinkFilter simply tests the method IlvGraphic.isSpline. Currently, IlvSplineLinkImage, IlvGeneralLink and IlvCompositeLink return true when certain link parameters are set so that they behave like splines. You can set your own spline link filter that is adapted to your IlvGraphic data structures if needed. Call:

Memory savings

The computation of a layout on a large graph may require a large amount of memory. Some layout algorithms optionally use two ways to store data: one which gives the priority to speed (this is the default case), the other which consumes less memory and is usually slower. The amount of memory savings depends, of course, on the implementation of the subclass of IlvGraphLayout. No matter which option you choose for memory savings, the resulting layout should be the same.

To enable memory savings:

Add to the GraphLayout section:

Use the method:

Memory savings is disabled by default.

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.

Percentage of completion calculation

Some layout algorithms can provide an estimation of how much of the layout has been completed. This estimation is made available as a percentage value that is stored in the graph layout report. When the algorithm starts, the percentage value is set to 0. The layout algorithm calls the following method from time to time to increase the percentage value by steps until it reaches 100:

The percentage value can be accessed from the layout report by using the following method:

To see an example of how to read the percentage value during the running of a layout, see Graph layout event listeners.

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Preserve fixed links

Sometimes, you want some links of the graph to be “pinned” (that is, to stay in their current shape when the layout is performed). You want a way to indicate the links that the layout algorithm cannot reshape. It makes sense especially when using a semiautomatic layout (the method where the user fine-tunes the layout by hand after the layout is completed) or when using an incremental layout (the method where the graph, the shape of the links, or both are modified after the layout has been performed, and then the layout is performed again).

To specify that a link is fixed:

Use the method:

If the fixed parameter is set to true, it means that the link is fixed. To obtain the current setting for a link:

The default value is false.

To remove the fixed attribute from all links in the grapher, use the method:

The fixed attributes on links are considered only if you additionally call the following statement:

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Preserve fixed nodes

At times, you might want some nodes of the graph to be “pinned” (that is, to stay in their current position when the layout is performed). You need a way to indicate the nodes that the layout algorithm cannot move. It makes sense especially when using a semiautomatic layout (the method where the user fine-tunes the layout by hand after the layout is completed) or when using an incremental layout (the method where the graph, the position of the nodes, or both are modified after the layout has been performed, and then the layout is performed again).

To specify that a node is fixed:

Use the method:

If the fixed parameter is set to true, it means that the node is fixed. To obtain the current setting for a node:

The default value is false.

To remove the fixed attribute from all nodes in the grapher, use the method:

The fixed attributes on nodes are considered only if you also call:

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. A subclass can override this method to return true to indicate that this mechanism is supported.

Random generator seed value

Some layout algorithms use random numbers (or randomly chosen parameters) for which they accept a user-defined seed value. For example, the Random Layout uses the random generator to compute the coordinates of the nodes. The Uniform Length Edges Layout uses the random generator to compute some internal variables.

Subclasses of IlvGraphLayout that are designed to support this mechanism allow the user to choose one of three ways of initializing the random generator:

The user chooses the initialization option depending on what happens when the layout algorithm is performed again on the same graph. If the same seed value is used, the same layout is produced, which may be the desired result. In other situations, the user may want to produce different layouts in order to select the best one. This can be achieved by performing the layout several times using different seed values.

To specify the seed value:

You can specify for instance the seed value 25 of the random generator by adding the following statements to the GraphLayout section:

The first statement defines the seed value, and the second statement specifies that the seed value must be used.

This example shows how this parameter can be used in Java in combination with the java.util.Random class in your implementation of the method IlvGraphLayout.layout():

To specify the seed value in Java, use the method:

The default seed value is 0.

The user-defined seed value is used only if you call additionally

To indicate whether a subclass of IlvGraphLayout supports this parameter, use the method:

The default implementation returns false. A subclass can override this method in order to return true to indicate that this parameter is supported.

Save parameters to named properties

There are many ways to store your graph and your parameters:

The base class IlvGraphLayout provides support for saving the layout parameters (such as isAnimate or isMemorySavings ) to .ivl files or to transfer the parameters to named properties. This is an advanced mechanism that is explained in detail in Saving layout parameters and preferred layouts. If you use XML files, CSS files, or databases, there is no point using this advanced mechanism.

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.

Stop immediately

Several layout algorithms can stop computation when an external event occurs, for instance when the user presses a “Stop” button.

To stop the layout, you can call:

This method is typically called in a multithreaded application from a separate thread that is not the layout thread. The method returns true if the stop was initiated and false if the algorithm cannot stop. The method returns immediately, but the layout thread usually needs some additional time after initiating the stop to clean up data structures.

The following code fragment illustrates the usage.

You start the layout in a separate thread:

The class GraphLayoutPerformer is an implementation of the interface Runnable that performs layout. The following code is a sketch of this class:

The Stop button operates outside the layout thread and simply calls the method stopImmediately of the running layout instance:

The consequences of stopping a layout process depend on the specific layout algorithm. Some layout algorithms have an iterative nature. Stopping the iteration process results in a slight loss of quality in the drawing, but the layout can still be considered valid. Other layout algorithms have a sequential nature. Interrupting the sequence of the layout steps might not result in a valid layout. Usually, these algorithms return to the situation before the start of the layout process.

To indicate whether a subclass of IlvGraphLayout supports this mechanism, use the method:

The default implementation returns false. You can write a subclass to override this method in order to return true to indicate that this mechanism is supported.

Use default parameters

All the generic parameters have a default value. After modifying parameters, you may want the layout algorithm to use the default values. Later, you may want to return to your customized values. Rogue Wave  JViews keeps the previous settings when you select the default values mode. In Java, you can switch between the default values mode and the mode for your own settings using the method:

To obtain the current value:

The default value is false. This means that any setting you make will be taken into consideration and the parameters that have not been specified will have their default values.