IBM ILOG Dojo Diagrammer 1.1 API Documentation
Legend: Array Boolean Constructor Date DomNode Error Function Namespace Number Object RegExp Singleton String

ibm_ilog.graphlayout.forcedirected.ForceDirectedLayout (version 1.1-SNAPSHOT)

Object » ibm_ilog.graphlayout.GraphLayout » ibm_ilog.graphlayout.basic.BasicLinkStyleLayout » ibm_ilog.graphlayout.forcedirected.ForceDirectedLayout

The main class for the Force-Directed Layout algorithm.

The Force-Directed Layout algorithm can be used to lay out any type of graph. It often provides a drawing with no, or only a few, edge crossings and with approximately equal-length edges for small- and medium-size graphs having a small number of cycles.

This layout algorithm iteratively searches for a configuration of the graph such that the lengths of the edges are close to a desired value.

Here are sample drawings produced with the Force-Directed Layout algorithm:

Sample drawing produced with the Force-Directed Layout

Sample drawing produced with the Force-Directed Layout

Sample drawing produced with the Force-Directed Layout

Sample drawing produced with the Force-Directed Layout

Performance hints

Several parameters have an impact on speed. In some extent, the performance can be improved by modifying these parameters.

  • Parameter with the largest impact on speed:
    • ForceDirectedLayout.setLayoutMode(). The algorithm provides three modes with different tradeoffs between quality and speed. For details, please refer to documentation of this method.
  • Parameters that allow to reduce the number of iterations that are executed:
    • ForceDirectedLayout.setPreferredLinksLength(). The algorithm stops iterating when the length of all links is close to the specified "preferredLinksLength" parameter. If the preferred length is very high while the initial length of the links is small, reducing the preferred length is an indirect way to reduce the necessary number of iterations, hence to speed up.
    • ibm_ilog.graphlayout.GraphLayout.setAllowedTime(). Reducing the allowed time is a way to force the completion of the layout quicker. However, the quality gets of course worst.
    • ForceDirectedLayout.setAllowedNumberOfIterations(). Similar as for ibm_ilog.graphlayout.GraphLayout.setAllowedTime().
  • Parameters that allow to reduce the time spent on each iteration:
    • ForceDirectedLayout.setRespectNodeSizes(). If disabled, the algorithm is a bit quicker because it does not try to avoid overlaps between nodes. This is in particular possible, without quality degradation, when all the nodes have approximately the same size and have more or less a square shape. In such cases, specifying a "preferredLinksLength" high enough usually avoids overlaps even if "respectNodeSizes" is not enabled.
    • ForceDirectedLayout.setMaxAllowedMovePerIteration(). This indicates the maximum distance the algorithm is allowed to move a node at each iteration. The higher the value, quicker the optimum may be reached, but also the algorithm may fail to converge (no "crash", just that the quality may be worst).

See the corresponding chapter of the IBM ILOG Dojo Diagrammer User's Manual for details on the algorithm, the types of graphs for which this algorithm can be used, the features and limitations, code samples, parameters, and so on.

You can specify a preferred length for the links globally ( ForceDirectedLayout.setPreferredLinksLength() or for specific links ( ForceDirectedLayout.setPreferredLength()).

You can request that the real size of the nodes is taken into account ( ForceDirectedLayout.setRespectNodeSizes()). This is especially recommended when the nodes are not square (have a larger or smaller width than height), or have different sizes. In such a case, the layout quality can be often further improved by increasing the weight of the node repulsion force (see ForceDirectedLayout.setAdditionalNodeRepulsionWeight(); the default is zero).

While the layout algorithm optionally restricts the region where the nodes are placed (see ForceDirectedLayout.setForceFitToLayoutRegion()), the layout quality is usually much better if this option is not used (this is the default behavior).

If this option is not set, the nodes are considered to be points located in the center of the bounding box of the nodes. Using the layout algorithm without setting this option is recommended when the width of the nodes is close to their height and there are no significant size differences among the nodes.

Note that, in the incremental mode (which is the default), the initial position of the nodes (at the moment you start the layout) is taken into account by the layout algorithm, so you may get different results depending on the initial position.

Property Summary

  • ALL_CORNERS Defines that all the corners are allowed for placing self-links (that is, links that start and end at the same node). This value is the combination of all the values described below: BasicLinkStyleLayout.TOP_LEFT: top left corner; BasicLinkStyleLayout.TOP_RIGHT: top right corner; BasicLinkStyleLayout.BOTTOM_RIGHT: bottom right corner; BasicLinkStyleLayout.BOTTOM_LEFT: bottom left corner.
  • BOTTOM_LEFT Defines the 'bottom left' corner as allowed corner to place self-links (that is, links that start and end at the same node).
  • BOTTOM_RIGHT Defines the 'bottom right' corner as allowed corner to place self-links (that is, links that start and end at the same node).
  • CENTERED Multiple self-link distribution: centered. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the middle of the bundles of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links.
  • CLOCK_WISE Self-link orientation: clockwise. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) are routed in clockwise orientation.
  • CONNECTED_ONE_BEND_BUNDLE Multilink mode: one bend polyline bundling with connection. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed with one bend to avoid overlaps. All links of the bundle are connected to the node and start at the same point and end at the same point.
  • CONNECTED_RECTANGULAR Self-link mode: rectangular self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node.
  • CONNECTED_SQUARE Self-link mode: square self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node.
  • COUNTER_CLOCK_WISE Self-link orientation: counterclockwise. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) are routed in counterclockwise orientation.
  • FAST_MULTILEVEL_MODE Fast multilevel layout mode. When used as an an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in fast multilevel mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
  • FREE_ONE_BEND_BUNDLE Multilink mode: one bend polyline bundling without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed with one bend to avoid overlaps. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection points. There is no guarantee that all links of the bundle start or end at a common point.
  • FREE_RECTANGULAR Self-link mode: rectangular self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR'. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
  • FREE_SQUARE Self-link mode: square self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.CONNECTED_SQUARE'. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
  • HORIZONTAL_TO_VERTICAL Self-link orientation: horizontal to vertical. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) start at the left or right side of the node with a horizontal segment and end at the top or bottom side of the node with a vertical segment.
  • INCREMENTAL_MODE Incremental layout mode. When used as an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in incremental mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
  • INNER Multiple self-link distribution: towards inner nestings. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the outermost self-link loop of a bundle of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links, and the remaining self-links loops are distributed towards the inner of the nestings.
  • LINK_LENGTH_PROPERTY
  • NARROW_CONNECTED_RECTANGULAR Self-link mode: narrow rectangular self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
  • NARROW_CONNECTED_SQUARE Self-link mode: narrow square self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.CONNECTED_SQUARE'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.CONNECTED_SQUARE', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
  • NARROW_FREE_RECTANGULAR Self-link mode: narrow rectangular self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR'. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.FREE_RECTANGULAR'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.FREE_RECTANGULAR', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links * is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
  • NARROW_FREE_SQUARE Self-link mode: narrow square self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE'. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.FREE_SQUARE'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.FREE_SQUARE', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
  • NARROW_STRAIGHT_LINE_BUNDLE Multilink mode: narrow straight bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed straight but shifted to avoid overlaps. The bundle may appear more narrow since the shift offset is limited by the size of the end nodes.
  • NON_INCREMENTAL_MODE Non-incremental layout mode. When used as an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in nonincremental mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
  • NO_BENDS Self-link mode: no reshape. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', self-links (that is, links that start and end at the same node) are not reshaped with bends and may not be visible after layout.
  • NO_BUNDLE Multilink mode: no bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are not spread out and will overlap.
  • NO_RESHAPE_STYLE No links reshape option. When used as an argument of ' ibm_ilog.graphlayout.basic.BasicLinkStyleLayout.setLinkStyle()', the links are not reshaped.
  • OUTER Multiple self-link distribution: towards outer nestings. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the innermost self-link loop of a bundle of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links, and the remaining self-link loops are distributed towards the outer of the nestings.
  • STRAIGHT_LINE_BUNDLE Multilink mode: straight bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed straight but shifted to avoid overlaps.
  • STRAIGHT_LINE_STYLE Straight-line links shape option. When used as an argument of ' ibm_ilog.graphlayout.basic.BasicLinkStyleLayout.setLinkStyle()', the links are given a straight-line shape.
  • TOP_LEFT Defines the 'top left' corner as allowed corner to place self-links (that is, links that start and end at the same node).
  • TOP_RIGHT Defines the 'top right' corner as allowed corner to place self-links (that is, links that start and end at the same node).
  • VERTICAL_TO_HORIZONTAL Self-link orientation: vertical to horizontal. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) start at the top or bottom side of the node with a vertical segment and end at the left or right side of the node with a horizontal segment.

Method Summary

  • constructor(a0) Returns a new instance of ' BasicLinkStyleLayoutNodeProperty' that stores the parameter settings of this layout class for nodes.
  • copy() returns ibm_ilog.graphlayout.GraphLayout Copies the layout instance.
  • copyParameters(source) Copies the parameters from a given layout instance.
  • createLayoutReport() returns ibm_ilog.graphlayout.GraphLayoutReport Creates the graph layout report instance.
  • detach() Detaches the graph model from the layout instance.
  • getAdditionalNodeRepulsionWeight() returns Number Returns the weight of the additional node repulsion force.
  • getAllowedNumberOfIterations() returns int Returns the maximum number of allowed iterations.
  • getConvergenceThreshold() returns Number Returns the threshold value for the convergence detection mechanism.
  • getLayoutCodeOnInterrupt() returns int Returns the layout code when the allowed time elapsed before completion of the layout.
  • getLayoutMode() returns int Returns the current layout mode.
  • getLinkLengthWeight() returns Number Returns the link length weight.
  • getLinkStyle() returns int Returns the current option for the style of the shape of the links.
  • getMaxAllowedMovePerIteration() returns Number Returns the maximum authorized move at each iteration of the layout algorithm.
  • getMaxPercentageOfElapsedTimeForRefinement() returns Number Returns the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is ' ForceDirectedLayout.FAST_MULTILEVEL_MODE' .
  • getMaxPercentageOfTotalAllowedTimeForRefinement() returns Number Returns the upper limit for the duration of the finetuning step in "fast multilevel" layout mode as percentage of the total allowed time.
  • getMaxRepeatForConvergence() returns int Returns the maximum number of attempts to reach convergence at each step when the layout mode is ' ForceDirectedLayout.FAST_MULTILEVEL_MODE' .
  • getMultiLinkMaxSpread() returns Number Returns the maximum spread width between multiple links between the same pair of nodes.
  • getMultiLinkMode() returns int Returns the current option for the mode how multiple links between the same pair of nodes are laid out.
  • getMultiLinkOffset() returns Number Returns the offset between multiple links between the same pair of nodes.
  • getMultiLinksCount() returns int Returns the number of multilinks.
  • getMultiSelfLinkDistribution() returns int Returns the current option for the distribution of bundles of multiple self-links (that is, multiple links that start and end at the same node).
  • getMultiSelfLinkMaxSpread() returns Number Returns the maximum spread width between multiple self-links (that is, multiple links that start and end at the same node).
  • getMultiSelfLinkOffset() returns Number Returns the offset between multiple self-links (that is, multiple links that start and end at the same node).
  • getNodeDistanceThreshold() returns Number Returns the node distance threshold.
  • getPercentagesOfCompletion() returns Array Returns an array of 4 integer numbers, denoting the percentage of completion for each of the 4 steps.
  • getPreferredLength(link) Returns the preferred length of a link; returns '-1' if the length is unspecified (in this case, the layout uses the global length; see ' ForceDirectedLayout.getPreferredLinksLength()').
  • getPreferredLinksLength() returns Number Returns the global preferred length of the links.
  • getSelfLinkAbsoluteAttachPosition() returns Point Returns the absolute attach position at the node border for self-links (that is, links that start and end at the same node).
  • getSelfLinkAllowedCorners() returns int Returns which corners are allowed to have self-links (that is, links that start and end at the same node).
  • getSelfLinkMode() returns int Returns the current option for the mode how self-links (that is, links that start and end at the same node) are laid out.
  • getSelfLinkOrientation() returns int Returns the current option for the orientation of self-links (that is, links that start and end at the same node).
  • getSelfLinkRelativeAttachPosition() returns Point Returns the relative attach position at the node border for self-links (that is, links that start and end at the same node).
  • getSelfLinkSpacing() returns Number Returns the minimal spacing between node border and the self-links (that is, links that start and end at the same node).
  • getSelfLinksCount() returns int Returns the number of self-links.
  • increasePercentageComplete(newPercentage) Increases the percentage of completion that is stored in the layout report to the input value.
  • init() Initializes instance variables.
  • internalLayout() Computes the layout using the Force-Directed Layout algorithm.
  • isConnectLinksToNodeCenters() returns Boolean Returns 'true' if the algorithm connects the links to the centers of the nodes.
  • isForceFitToLayoutRegion() returns Boolean Returns the current choice for the force-fit-to-layout-region parameter.
  • isInterrupted() returns Boolean Returns 'true' if the layout is interrupted.
  • isLayoutOfConnectedComponentsEnabledByDefault() returns Boolean Overridden version of the method from the superclass that always returns 'true'.
  • isRespectNodeSizes() returns Boolean Returns 'true' if the algorithm tries to respect the size of the nodes.
  • isSelfLinkConnectToNodeCenter() returns Boolean Returns whether self-links (that is, links that start and end at the same node) connect towards the node center.
  • layout() Computes the layout using the Basic Link Style Layout algorithm.
  • setAdditionalNodeRepulsionWeight(weight) Sets the weight of the additional node repulsion force.
  • setAllowedNumberOfIterations(iterations) Sets the maximum number of iterations of the layout algorithm.
  • setConnectLinksToNodeCenters(enable) Sets whether the algorithm connects the links to the centers of the nodes.
  • setConvergenceThreshold(threshold) Sets the threshold value for the convergence detection mechanism.
  • setForceFitToLayoutRegion(option) Sets whether the layout algorithm must force the graph drawing to fit the layout region.
  • setLayoutMode(mode) Sets the layout mode.
  • setLinkLengthWeight(weight) Sets the link length weight.
  • setLinkStyle(style) Sets the style of the shape of the links.
  • setMaxAllowedMovePerIteration(maxMove) Sets the maximum authorized node move at each iteration of the layout algorithm.
  • setMaxPercentageOfElapsedTimeForRefinement(percentage) Sets the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is ' ForceDirectedLayout.FAST_MULTILEVEL_MODE' .
  • setMaxPercentageOfTotalAllowedTimeForRefinement(percentage) Sets the maximum percentage of the total allowed time that should be spent on the final refinement step when the layout mode is ' ForceDirectedLayout.FAST_MULTILEVEL_MODE' .
  • setMaxRepeatForConvergence(repeat) Sets the maximum number of attempts to reach convergence at each step when the layout mode is ' ForceDirectedLayout.FAST_MULTILEVEL_MODE' .
  • setMultiLinkMaxSpread(maxSpread) Sets the maximum spread width between multiple links between the same pair of nodes.
  • setMultiLinkMode(mode) Sets the mode how multiple links between the same pair of nodes are laid out.
  • setMultiLinkOffset(offset) Sets the offset between multiple links between the same pair of nodes.
  • setMultiSelfLinkDistribution(distribution) Sets the distribution of bundles of multiple self-links (that is, multiple links that start and end at the same node).
  • setMultiSelfLinkMaxSpread(maxSpread) Sets the maximum spread width between multiple self-links (that is, multiple links that start and end at the same node).
  • setMultiSelfLinkOffset(offset) Sets the offset between multiple self-links (that is, multiple links that start and end at the same node).
  • setNodeDistanceThreshold(threshold) Sets the node distance threshold.
  • setPreferredLength(link, length) Sets the preferred length of a link.
  • setPreferredLinksLength(length) Sets the global preferred length of the links.
  • setRespectNodeSizes(respect) Sets whether the algorithm must try to respect the size of the nodes.
  • setSelfLinkAbsoluteAttachPosition(position) Sets the absolute attach position at the node border for self-links (that is, links that start and end at the same node).
  • setSelfLinkAllowedCorners(corners) Sets which corners are allowed to have self-links (that is, links that start and end at the same node).
  • setSelfLinkConnectToNodeCenter(enable) Sets whether self-links (that is, links that start and end at the same node) connect towards the node center.
  • setSelfLinkMode(mode) Sets the mode how self-links (that is, links that start and end at the same node) are laid out.
  • setSelfLinkOrientation(orientation) Sets the orientation of self-links (that is, links that start and end at the same node).
  • setSelfLinkRelativeAttachPosition(position) Sets the relative attach position at the node border for self-links (that is, links that start and end at the same node).
  • setSelfLinkSpacing(spacing) Sets the minimal spacing between node border and self-links (that is, links that start and end at the same node).
  • supportsAllowedTime() returns Boolean Indicates that this layout class can stop the layout computation when the user-defined allowed time is exceeded.
  • supportsLayoutOfConnectedComponents() returns Boolean Indicates that this layout class can cut the attached graph into connected components, apply itself to each connected component separately, and then use the layout instance returned by the method ' ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents()' to position the connected components.
  • supportsLayoutRegion() returns Boolean Indicates that this layout class can control the size of the graph drawing to fit (approximately) a user-defined region (a rectangle).
  • supportsLinkConnectionBox() returns Boolean Indicates that this layout class can use a link connection box interface to calculate the end points of a link.
  • supportsPercentageComplete() returns Boolean Indicates that this layout class can not estimate the percentage of completion during the layout run.
  • supportsPreserveFixedLinks() returns Boolean Indicates that this layout class allows the user to specify fixed links.
  • supportsPreserveFixedNodes() returns Boolean Indicates that this layout class allows the user to specify fixed nodes.
  • supportsStopImmediately() returns Boolean Indicates that this layout class can interrupt the current run of the layout immediately in a controlled way.

Properties

ALL_CORNERS
Defines that all the corners are allowed for placing self-links (that is, links that start and end at the same node). This value is the combination of all the values described below: BasicLinkStyleLayout.TOP_LEFT: top left corner; BasicLinkStyleLayout.TOP_RIGHT: top right corner; BasicLinkStyleLayout.BOTTOM_RIGHT: bottom right corner; BasicLinkStyleLayout.BOTTOM_LEFT: bottom left corner.
BOTTOM_LEFT
Defines the 'bottom left' corner as allowed corner to place self-links (that is, links that start and end at the same node).
BOTTOM_RIGHT
Defines the 'bottom right' corner as allowed corner to place self-links (that is, links that start and end at the same node).
CENTERED
Multiple self-link distribution: centered. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the middle of the bundles of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links.
CLOCK_WISE
Self-link orientation: clockwise. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) are routed in clockwise orientation.
CONNECTED_ONE_BEND_BUNDLE
Multilink mode: one bend polyline bundling with connection. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed with one bend to avoid overlaps. All links of the bundle are connected to the node and start at the same point and end at the same point.
CONNECTED_RECTANGULAR
Self-link mode: rectangular self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node.
CONNECTED_SQUARE
Self-link mode: square self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node.
COUNTER_CLOCK_WISE
Self-link orientation: counterclockwise. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) are routed in counterclockwise orientation.
FAST_MULTILEVEL_MODE
Fast multilevel layout mode. When used as an an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in fast multilevel mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
FREE_ONE_BEND_BUNDLE
Multilink mode: one bend polyline bundling without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed with one bend to avoid overlaps. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection points. There is no guarantee that all links of the bundle start or end at a common point.
FREE_RECTANGULAR
Self-link mode: rectangular self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR'. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
FREE_SQUARE
Self-link mode: square self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.CONNECTED_SQUARE'. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
HORIZONTAL_TO_VERTICAL
Self-link orientation: horizontal to vertical. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) start at the left or right side of the node with a horizontal segment and end at the top or bottom side of the node with a vertical segment.
INCREMENTAL_MODE
Incremental layout mode. When used as an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in incremental mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
INNER
Multiple self-link distribution: towards inner nestings. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the outermost self-link loop of a bundle of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links, and the remaining self-links loops are distributed towards the inner of the nestings.
LINK_LENGTH_PROPERTY
NARROW_CONNECTED_RECTANGULAR
Self-link mode: narrow rectangular self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.CONNECTED_RECTANGULAR', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
NARROW_CONNECTED_SQUARE
Self-link mode: narrow square self-links with 3 bends and connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.CONNECTED_SQUARE'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.CONNECTED_SQUARE', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
NARROW_FREE_RECTANGULAR
Self-link mode: narrow rectangular self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR'. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.FREE_RECTANGULAR'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.FREE_RECTANGULAR', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links * is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
NARROW_FREE_SQUARE
Self-link mode: narrow square self-links with 3 bends without enforced connection. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', 3 bends are added to self-links (that is, links that start and end at the same node). The bends are placed at the same position like ' BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE'. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. For single self-links, this mode has the same effect like ' BasicLinkStyleLayout.FREE_SQUARE'. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from ' BasicLinkStyleLayout.FREE_SQUARE', as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point.
NARROW_STRAIGHT_LINE_BUNDLE
Multilink mode: narrow straight bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed straight but shifted to avoid overlaps. The bundle may appear more narrow since the shift offset is limited by the size of the end nodes.
NON_INCREMENTAL_MODE
Non-incremental layout mode. When used as an argument of ' ForceDirectedLayout.setLayoutMode()', the layout is executed in nonincremental mode. For details, see ' ForceDirectedLayout.setLayoutMode()'.
NO_BENDS
Self-link mode: no reshape. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkMode()', self-links (that is, links that start and end at the same node) are not reshaped with bends and may not be visible after layout.
NO_BUNDLE
Multilink mode: no bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are not spread out and will overlap.
NO_RESHAPE_STYLE
No links reshape option. When used as an argument of ' ibm_ilog.graphlayout.basic.BasicLinkStyleLayout.setLinkStyle()', the links are not reshaped.
OUTER
Multiple self-link distribution: towards outer nestings. When used as an argument of ' BasicLinkStyleLayout.setMultiSelfLinkDistribution()', the innermost self-link loop of a bundle of multiple self-links (that is, multiple links that start and end at the same node) is attached at the reference points for self-links, and the remaining self-link loops are distributed towards the outer of the nestings.
STRAIGHT_LINE_BUNDLE
Multilink mode: straight bundling. When used as an argument of ' BasicLinkStyleLayout.setMultiLinkMode()', multiple links between the same pair of nodes are routed straight but shifted to avoid overlaps.
STRAIGHT_LINE_STYLE
Straight-line links shape option. When used as an argument of ' ibm_ilog.graphlayout.basic.BasicLinkStyleLayout.setLinkStyle()', the links are given a straight-line shape.
TOP_LEFT
Defines the 'top left' corner as allowed corner to place self-links (that is, links that start and end at the same node).
TOP_RIGHT
Defines the 'top right' corner as allowed corner to place self-links (that is, links that start and end at the same node).
VERTICAL_TO_HORIZONTAL
Self-link orientation: vertical to horizontal. When used as an argument of ' BasicLinkStyleLayout.setSelfLinkOrientation()', self-links (that is, links that start and end at the same node) start at the top or bottom side of the node with a vertical segment and end at the left or right side of the node with a horizontal segment.

Methods

constructor

Returns a new instance of BasicLinkStyleLayoutNodeProperty that stores the parameter settings of this layout class for nodes.

The method is used by ibm_ilog.graphlayout.AbstractGraphLayoutModel.saveParametersToNamedProperties() to create a named property for a node that contains parameter settings of this layout instance for the input node.

ParameterTypeDescription
a0
copy
Returns ibm_ilog.graphlayout.GraphLayout: A copy of the layout instance.

Copies the layout instance.

This method copies the layout instance by calling the copy constructor.

When performing a recursive layout of a nested graph, this method is used by ibm_ilog.graphlayout.ILayoutProvider to "clone" the layout instance of a parent graph.

Note that the parameters which are specific to a node or a link are not copied. The other parameters, including the layout region specification and the customization interfaces, are also copied. A copy of the layout instance used for laying out the connected components is set on the new instance.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

copyParameters

Copies the parameters from a given layout instance.

Note that the parameters which are specific to a node or a link are not copied. The other parameters, including the layout region specification and the customization interfaces, are also copied. A copy of the layout instance used for laying out the connected components is set on this layout instance.

If a method of the type supportsXXX is associated with a parameter, the parameter is copied only if the corresponding method returns true.

ParameterTypeDescription
source
createLayoutReport
Returns ibm_ilog.graphlayout.GraphLayoutReport: A new instance of graph layout report. The current implementation creates an instance of ' ForceDirectedLayoutReport'.
Creates the graph layout report instance.
detach

Detaches the graph model from the layout instance. When you attach a new graph model to the layout instance, you do not need to detach the old graph model because this is done automatically when you call ibm_ilog.graphlayout.GraphLayout.attach().

The method performs cleaning operations on the graph model.

Note that you must call this method when you no longer need the layout instance. Otherwise, some objects may not be garbage collected.

getAdditionalNodeRepulsionWeight
Returns Number
Returns the weight of the additional node repulsion force.
getAllowedNumberOfIterations
Returns int
Returns the maximum number of allowed iterations.
getConvergenceThreshold
Returns Number
Returns the threshold value for the convergence detection mechanism.
getLayoutCodeOnInterrupt
Returns int: ' ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_VALID'

Returns the layout code when the allowed time elapsed before completion of the layout.

getLayoutMode
Returns int
Returns the current layout mode.
getLinkLengthWeight
Returns Number
Returns the link length weight.
getLinkStyle
Returns int
Returns the current option for the style of the shape of the links.
getMaxAllowedMovePerIteration
Returns Number
Returns the maximum authorized move at each iteration of the layout algorithm.
getMaxPercentageOfElapsedTimeForRefinement
Returns Number

Returns the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is ForceDirectedLayout.FAST_MULTILEVEL_MODE .

getMaxPercentageOfTotalAllowedTimeForRefinement
Returns Number
Returns the upper limit for the duration of the finetuning step in "fast multilevel" layout mode as percentage of the total allowed time.
getMaxRepeatForConvergence
Returns int

Returns the maximum number of attempts to reach convergence at each step when the layout mode is ForceDirectedLayout.FAST_MULTILEVEL_MODE .

getMultiLinkMaxSpread
Returns Number
Returns the maximum spread width between multiple links between the same pair of nodes.
getMultiLinkMode
Returns int
Returns the current option for the mode how multiple links between the same pair of nodes are laid out.
getMultiLinkOffset
Returns Number
Returns the offset between multiple links between the same pair of nodes.
getMultiLinksCount
Returns int: The number of multilinks.

Returns the number of multilinks. Can be used by subclasses inside BasicLinkStyleLayout.internalLayout() to test how many multilinks have to be treated.

getMultiSelfLinkDistribution
Returns int
Returns the current option for the distribution of bundles of multiple self-links (that is, multiple links that start and end at the same node).
getMultiSelfLinkMaxSpread
Returns Number
Returns the maximum spread width between multiple self-links (that is, multiple links that start and end at the same node).
getMultiSelfLinkOffset
Returns Number
Returns the offset between multiple self-links (that is, multiple links that start and end at the same node).
getNodeDistanceThreshold
Returns Number
Returns the node distance threshold.
getPercentagesOfCompletion
Returns Array: An array of 4 integer numbers, denoting the percentage of completion.

Returns an array of 4 integer numbers, denoting the percentage of completion for each of the 4 steps. The steps are the following:

  1. After collecting multilinks and self-links.
  2. After calling BasicLinkStyleLayout.internalLayout().
  3. After treating all multilinks.
  4. After treating all self-links.
This method can be overridden by subclasses.

getPreferredLength
The preferred length of a link, if one is specified; or '-1' if the layout uses the global length.
Returns the preferred length of a link; returns '-1' if the length is unspecified (in this case, the layout uses the global length; see ' ForceDirectedLayout.getPreferredLinksLength()').
ParameterTypeDescription
linkObjectThe link instance.
getPreferredLinksLength
Returns Number
Returns the global preferred length of the links.
getSelfLinkAbsoluteAttachPosition
Returns Point

Returns the absolute attach position at the node border for self-links (that is, links that start and end at the same node). The absolute attach position is expressed as absolute coordinate units.

getSelfLinkAllowedCorners
Returns int: A bitwise-Or combination of the following values:
  • ' BasicLinkStyleLayout.TOP_LEFT': top left corner.
  • ' BasicLinkStyleLayout.TOP_RIGHT': top right corner.
  • ' BasicLinkStyleLayout.BOTTOM_RIGHT': bottom right corner.
  • ' BasicLinkStyleLayout.BOTTOM_LEFT': bottom left corner.
or the value ' BasicLinkStyleLayout.ALL_CORNERS'.

Returns which corners are allowed to have self-links (that is, links that start and end at the same node). The default value is all the corners, that is, a combination of all the possible values.

getSelfLinkMode
Returns int
Returns the current option for the mode how self-links (that is, links that start and end at the same node) are laid out.
getSelfLinkOrientation
Returns int
Returns the current option for the orientation of self-links (that is, links that start and end at the same node).
getSelfLinkRelativeAttachPosition
Returns Point

Returns the relative attach position at the node border for self-links (that is, links that start and end at the same node). The relative attach position is expressed as a fraction of the width and height of the node bounding box. Self-links occur at a corner of the node, and the relative position is specified with respect to this corner.

getSelfLinkSpacing
Returns Number
Returns the minimal spacing between node border and the self-links (that is, links that start and end at the same node).
getSelfLinksCount
Returns int: The number of self-links.

Returns the number of self-links. Can be used by subclasses inside BasicLinkStyleLayout.internalLayout() to test how many self-links have to be treated.

increasePercentageComplete

Increases the percentage of completion that is stored in the layout report to the input value. Layout algorithms that support the percentage complete feature should call this method during the running of the layout. This method does not set the percentage to a lower value than the previous value. It also does not set the value to more than 100%. It silently ignores wrong input values.

ParameterTypeDescription
newPercentageintNew percentage of completion
init

Initializes instance variables.

You should not call this method directly. The method is called internally by the constructor without arguments and by the copy constructor. The method must be overridden by subclasses that need to initialize additional instance variables.

internalLayout

Computes the layout using the Force-Directed Layout algorithm. To start the layout, call the method ibm_ilog.graphlayout.GraphLayout.performLayout(). Note that this class overrides the ForceDirectedLayout.createLayoutReport() and creates an instance of ForceDirectedLayoutReport.

isConnectLinksToNodeCenters
Returns Boolean
Returns 'true' if the algorithm connects the links to the centers of the nodes.
isForceFitToLayoutRegion
Returns Boolean
Returns the current choice for the force-fit-to-layout-region parameter.
isInterrupted
Returns Boolean: 'true' if the layout is interrupted.
Returns 'true' if the layout is interrupted.
isLayoutOfConnectedComponentsEnabledByDefault
Returns Boolean: 'true'
Overridden version of the method from the superclass that always returns 'true'.
isRespectNodeSizes
Returns Boolean
Returns 'true' if the algorithm tries to respect the size of the nodes.
isSelfLinkConnectToNodeCenter
Returns Boolean
Returns whether self-links (that is, links that start and end at the same node) connect towards the node center.
layout

Computes the layout using the Basic Link Style Layout algorithm. To start the layout, call the method ibm_ilog.graphlayout.GraphLayout.performLayout(). Subclasses should not override this method but should override BasicLinkStyleLayout.internalLayout() instead.

setAdditionalNodeRepulsionWeight

Sets the weight of the additional node repulsion force. This weight is a multiplier which is applied to the repulsion force between two nodes that are not connected by a link. The additional repulsion force is applied only if the distance between the nodes is smaller than the node distance threshold (see ForceDirectedLayout.setNodeDistanceThreshold()).

The default value is 0.2. Increasing the weight increases the priority that is given to maintaining the nodes at a distance larger than the node distance threshold. However, increasing the weight decreases the ability of the algorithm to reach convergence quickly.

ParameterTypeDescription
weight
setAllowedNumberOfIterations

Sets the maximum number of iterations of the layout algorithm. The default value is 1000.

ParameterTypeDescription
iterations
setConnectLinksToNodeCenters

Sets whether the algorithm connects the links to the centers of the nodes. This option has only an effect if the link style is not BasicLinkStyleLayout.NO_RESHAPE_STYLE. If the argument is true, the links are connected to the center of the nodes. If a link connection box is set, it uses the virtual center of the connection box instead of the center of the bounding boxes of the end nodes. The virtual center is defined as the center of the connection box shifted by the average of the tangential "top" and "bottom" offset in the horizontal direction and by the average of the tangential "left" and "right" offset in the vertical direction. For instance, if the tangential offset is 20 at the top side and 10 at all other sides, the average shift offset is (20 + 10)/2 = 15 in the horizontal direction and (10 + 10)/2 = 10 in the vertical direction; hence the virtual center is at connectionBox.center() + (15, 10).

The default value is true.

ParameterTypeDescription
enable
setConvergenceThreshold

Sets the threshold value for the convergence detection mechanism. The iterative algorithm is stopped if the greatest movement of a node at an iteration ForceDirectedLayout.getMaxAllowedMovePerIteration() is smaller than threshold during several successive iterations.

The default value is 1. The units are in the same coordinate space as the coordinates and size of the nodes. Increasing this value may speed up the layout because the iterations may be stopped earlier. However, this may produce a nonoptimal layout. Decreasing this value in some cases improves the quality of the layout but needs more time because more iterations are performed. Note that if the specified value is too small, the iterations cannot be stopped until the allowed time or the allowed number of iterations is reached.

ParameterTypeDescription
threshold
setForceFitToLayoutRegion

Sets whether the layout algorithm must force the graph drawing to fit the layout region. If the argument is false (which is the default), the layout algorithm is free to move nodes outside the layout region. Note that the layout may not be optimal if the size of the layout region is too small. It is recommended to avoid forcing the use of a layout region anytime this is possible.

ParameterTypeDescription
option
setLayoutMode

Sets the layout mode. Valid values are:

  • ForceDirectedLayout.INCREMENTAL_MODE - The algorithm starts from the current position and iteratively tries to converge towards the optimal layout. Thus, in some cases, this mode avoids a major reorganization of the graph, which helps to preserve the "mental map" of the user as much as possible. However, this approach is not guaranteed, and depends on how far the initial position of the nodes is from the position that satisfies the criteria of the algorithm.
  • ForceDirectedLayout.NON_INCREMENTAL_MODE - The algorithm is free to reorganize the graph without trying to stay close to the initial positions. Often, the nonincremental mode is faster than the incremental mode, sometimes at the price of lower quality.
  • ForceDirectedLayout.FAST_MULTILEVEL_MODE - The algorithm uses a multilevel graph decomposition strategy that usually leads to significant speed gain. In this mode, the behavior is nonincremental.

The default value is ForceDirectedLayout.INCREMENTAL_MODE .

ParameterTypeDescription
mode
setLinkLengthWeight

Sets the link length weight. This weight is a multiplier that is applied when two nodes connected by a link are moved in order to obtain a link length close to the preferred value (see ForceDirectedLayout.setPreferredLinksLength() and ForceDirectedLayout.setPreferredLength()). The default value is 1. Increasing (or decreasing) this value increases (or decreases) the priority that is given to the link length criteria with respect to the minimum distance between nodes not connected by a link.

ParameterTypeDescription
weight
setLinkStyle

Sets the style of the shape of the links. Valid values are BasicLinkStyleLayout.STRAIGHT_LINE_STYLE (the links are given a straight-line shape) and BasicLinkStyleLayout.NO_RESHAPE_STYLE (no reshape is performed on the links).

This feature can be useful if the graph contains links that have intermediate points and are not straight-line links, for instance, ilog.diagrammer.model.DiagrammerLink links with intermediate points.

The default value is BasicLinkStyleLayout.STRAIGHT_LINE_STYLE.

ParameterTypeDescription
styleintThe link style value.
setMaxAllowedMovePerIteration

Sets the maximum authorized node move at each iteration of the layout algorithm. The default value is 5.

Increasing this parameter may speed up the layout, but the algorithm may fail to converge. Decreasing this parameter slows down the layout but in some cases improves the convergence. You should not specify a zero value, because in this case the layout cannot move the nodes at all.

ParameterTypeDescription
maxMove
setMaxPercentageOfElapsedTimeForRefinement

Sets the maximum percentage of the time already elapsed that should be spent on the final refinement step when the layout mode is ForceDirectedLayout.FAST_MULTILEVEL_MODE . The parameter has no effect in other layototut modes.

If the specified value is negative, the value 0 is used.

The default value is 1000 percent. That is, the refinement step should not take longer than 10 times the time already spent before this step.

Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

ParameterTypeDescription
percentage
setMaxPercentageOfTotalAllowedTimeForRefinement

Sets the maximum percentage of the total allowed time that should be spent on the final refinement step when the layout mode is ForceDirectedLayout.FAST_MULTILEVEL_MODE . The parameter has no effect in other layout modes.

If the specified value is negative, the value 0 is used.

The default value is 1O percent. Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

ParameterTypeDescription
percentage
setMaxRepeatForConvergence

Sets the maximum number of attempts to reach convergence at each step when the layout mode is ForceDirectedLayout.FAST_MULTILEVEL_MODE . The parameter has no effect in other layout modes.

If the specified value is less than 0, the value 1 is used.

The default value is 3. Increasing the value of this parameter may increase the quality of the layout, possibly at the price of a lower speed.

ParameterTypeDescription
repeat
setMultiLinkMaxSpread

Sets the maximum spread width between multiple links between the same pair of nodes.

If the multilink mode is BasicLinkStyleLayout.STRAIGHT_LINE_BUNDLE or BasicLinkStyleLayout.NARROW_STRAIGHT_LINE_BUNDLE, the multiple straight line links are shifted relative to each other to avoid overlaps. If the multilink mode is BasicLinkStyleLayout.CONNECTED_ONE_BEND_BUNDLE or BasicLinkStyleLayout.FREE_ONE_BEND_BUNDLE, bends are added to the multiple links to avoid that those links overlap. The straight links, or the multilink bends, respectively, are shifted relative to each other by the multilink offset unless the number of links times the offset exceeds the max spread value. In that case, the offset is limited by the max spread value. If the multilink mode is BasicLinkStyleLayout.NARROW_STRAIGHT_LINE_BUNDLE, the offset is further limited by the node size. If the multilink mode is BasicLinkStyleLayout.NO_BUNDLE, the maximum spread width has no effect.

This maximum spread width affects only links that are no self-links. See BasicLinkStyleLayout.setMultiSelfLinkMaxSpread() for the same parameter at self-links.

The default maximum spread value is 50.

ParameterTypeDescription
maxSpreadNumberThe maximum spread value.
setMultiLinkMode

Sets the mode how multiple links between the same pair of nodes are laid out. Valid values are:

  • BasicLinkStyleLayout.NO_BUNDLE - no bundling. Multiple links between the same pair of nodes are not spread out and will overlap.
  • BasicLinkStyleLayout.STRAIGHT_LINE_BUNDLE - straight line bundling. Multiple links between the same pair of nodes are routed as straight lines but shifted relative to each other to avoid overlaps. Different to the narrow mode, the shift offset is not limited by the node size.
  • BasicLinkStyleLayout.NARROW_STRAIGHT_LINE_BUNDLE - narrow straight line bundling (the default). Multiple links between the same pair of nodes are routed as straight lines but shifted relative to each other to avoid overlaps. The bundle may appear more narrow since the shift offset is limited by the size of the end nodes.
  • BasicLinkStyleLayout.CONNECTED_ONE_BEND_BUNDLE - one bend polyline bundling with connection. Multiple links between the same pair of nodes are routed with one bend to avoid overlaps. All links of the bundle are connected to the node and start at the same point and end at the same point.
  • BasicLinkStyleLayout.FREE_ONE_BEND_BUNDLE - one bend polyline bundling without enforced connection. Multiple links between the same pair of nodes are routed with one bend to avoid overlaps. The link connection point is not enforced, that is, the node and link are free to decide themselves where to place the connection point. There is no guarantee that all links of the bundle start or end at a common point.
This feature is only useful if the graph contains pairs of nodes that have multiple links in between. If has only an effect when the link style is not BasicLinkStyleLayout.NO_RESHAPE_STYLE.

ParameterTypeDescription
modeintThe multilink mode value.
setMultiLinkOffset

Sets the offset between multiple links between the same pair of nodes. If the multilink mode is BasicLinkStyleLayout.STRAIGHT_LINE_BUNDLE or BasicLinkStyleLayout.NARROW_STRAIGHT_LINE_BUNDLE, it is the offset between the the multiple straight line links. If the multilink mode is BasicLinkStyleLayout.CONNECTED_ONE_BEND_BUNDLE or BasicLinkStyleLayout.FREE_ONE_BEND_BUNDLE, it is the offset between the bends that are added to the multiple links to avoid that those links overlap. If the multilink mode is BasicLinkStyleLayout.NO_BUNDLE, the offset has no effect.

The straight links, or the multilink bends, respectively, are shifted relative to each other by the multilink offset unless the number of links times the offset exceeds the max spread value. In that case, the offset is limited by the max spread value. If the multilink mode is BasicLinkStyleLayout.NARROW_STRAIGHT_LINE_BUNDLE, the offset is further limited by the node size.

This offset affects only links that are no self-links. See BasicLinkStyleLayout.setMultiSelfLinkOffset() for the same parameter at self-links.

The default value is 10.

ParameterTypeDescription
offsetNumberThe offset value.
setMultiSelfLinkDistribution

Sets the distribution of bundles of multiple self-links (that is, multiple links that start and end at the same node). Self-link bundles form essentially nested rectangles or circles. There is a reference point at the node border and this reference point is either in the middle of the bundle, or at the outermost circle or at the innermost cicle. Valid values are:

  • BasicLinkStyleLayout.CENTERED - centered (default). The middle of a bundle of multiple self-links is attached at the reference points for self-links. The nested circles are equally spread out towards the inner nesting and towards the outer nesting.
  • BasicLinkStyleLayout.OUTER - towards outer nestings. The innermost self-link of a bundle of multiple self-links is attached at the reference points for self-links and the remaining self-links are distributed towards the outer of the nestings.
  • BasicLinkStyleLayout.INNER - towards inner nestings. The outermost self-link of a bundle of multiple self-links is attached at the reference points for self-links and the remaining self-links are distributed towards the inner of the nestings.
This feature is only useful if the graph contains bundles of multiple self-links. If has only an effect when the link style is not BasicLinkStyleLayout.NO_RESHAPE_STYLE and the self-link mode is not BasicLinkStyleLayout.NO_BENDS.

ParameterTypeDescription
distributionintThe distribution mode for multiple self-links.
setMultiSelfLinkMaxSpread

Sets the maximum spread width between multiple self-links (that is, multiple links that start and end at the same node).

If the self-link mode is not BasicLinkStyleLayout.NO_BENDS, bends are added to self-links. If there are multiple self-links at the same node, the bends are shifted relative to each other by the multiple self-link offset unless the number of self-links times the offset exceeds the max spread value. In that case, the offset is limited by the max spread value. If the self-link mode is BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR, BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE, BasicLinkStyleLayout.NARROW_FREE_RECTANGULAR, or BasicLinkStyleLayout.NARROW_FREE_SQUARE, the offset is further limited by the node size. If the self-link mode is BasicLinkStyleLayout.NO_BENDS, the maximum spread width has no effect.

This maximum spread width affects only self-links, no other multilinks. See BasicLinkStyleLayout.setMultiLinkMaxSpread() for the same parameter at other multilinks.

The default maximum spread value is 50.

ParameterTypeDescription
maxSpreadNumberThe maximum spread value.
setMultiSelfLinkOffset

Sets the offset between multiple self-links (that is, multiple links that start and end at the same node).

If the self-link mode is not BasicLinkStyleLayout.NO_BENDS, bends are added to self-links. If there are multiple self-links at the same node, the bends are shifted relative to each other by the multiple self-link offset unless the number of self-links times the offset exceeds the multiple self-link max spread value. In that case, the offset is limited by the max spread value. If the self-link mode is BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR, BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE, BasicLinkStyleLayout.NARROW_FREE_RECTANGULAR, or BasicLinkStyleLayout.NARROW_FREE_SQUARE, the offset is further limited by the node size. If the self-link mode is BasicLinkStyleLayout.NO_BENDS, the offset has no effect.

This offset affects only self-links, no other multilinks. See BasicLinkStyleLayout.setMultiLinkOffset() for the same parameter at other multilinks.

The default value is 10.

ParameterTypeDescription
offsetNumberThe offset value.
setNodeDistanceThreshold

Sets the node distance threshold. The additional repulsion force (see ForceDirectedLayout.setAdditionalNodeRepulsionWeight()) is applied only for nodes that are not connected by a link and are at a distance smaller than this threshold.

The default value is 30.

Note that the additional repulsion force is applied only if the corresponding weight (see ForceDirectedLayout.setAdditionalNodeRepulsionWeight()) is larger than 0. The default weight is 0; therefore, the node distance threshold has no effect if the weight is not modified.

ParameterTypeDescription
threshold
setPreferredLength

Sets the preferred length of a link. The layout algorithm tries to compute a layout where the link has the specified length. If a preferred length is set for a link, this overrides the global preferred length for this link.

After having specified a length for a link, you can call the method with a strictly negative value to indicate that the global preferred length must be used again for this link.

By default, no length is specified for the individual links.

ParameterTypeDescription
linkObjectThe link instance.
lengthNumberThe preferred length of the link.
setPreferredLinksLength

Sets the global preferred length of the links. The layout algorithm tries to compute a layout where the links have the specified length. The preferred length can also be specified individually for each link (or for some links). If an individual length is not specified for a particular link, the global length specified using this method is used for this link.

The default value is 60.

ParameterTypeDescription
length
setRespectNodeSizes

Sets whether the algorithm must try to respect the size of the nodes. If the argument is true, the preferred length parameter is interpreted as a minimum distance between the bounding boxes of the end nodes. Otherwise, the preferred length parameter is considered as the center-to-center distance between the end nodes.

ParameterTypeDescription
respect
setSelfLinkAbsoluteAttachPosition

Sets the absolute attach position at the node border for self-links (that is, links that start and end at the same node). The x value of the position specifies a point at the top or bottom border of the node, and the y value of the position specifies a point at the left or right border of the node. The absolute attach position is expressed as absolute coordinate units. Self-links occur at a corner of the node, and the relative position is specified with respect to this corner. For instance, if the self-link occurs at the bottom right corner, the attach position (10, 20) specifies that the self-link goes from 10 units away from the corner at the bottom side (that is, x = node.x + node.width - 10) to 20 units away from the corner at the right side (that is, y = node.y + node.height - 20).

If the self-link mode is BasicLinkStyleLayout.CONNECTED_SQUARE, BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE, BasicLinkStyleLayout.FREE_SQUARE, or BasicLinkStyleLayout.NARROW_FREE_SQUARE, then the attach position is only respected at one side and calculate on the other side to form a square.

The real attach position is the sum of the relative attach position

The real attach position is the sum of the relative attach position and the absolute attach position.

The default value of the absolute attach position is (0, 0).

ParameterTypeDescription
positionPointThe absolute attach position for self-links.
setSelfLinkAllowedCorners

Sets which corners are allowed to have self-links (that is, links that start and end at the same node). The default value is BasicLinkStyleLayout.ALL_CORNERS, that is, a combination of all the possible values:

  • BasicLinkStyleLayout.TOP_LEFT: top left corner.
  • BasicLinkStyleLayout.TOP_RIGHT: top right corner.
  • BasicLinkStyleLayout.BOTTOM_RIGHT: bottom right corner.
  • BasicLinkStyleLayout.BOTTOM_LEFT: bottom left corner.

ParameterTypeDescription
cornersintA bitwise-Or combination of the following values: BasicLinkStyleLayout.TOP_LEFT: top left corner; BasicLinkStyleLayout.TOP_RIGHT: top right corner; BasicLinkStyleLayout.BOTTOM_RIGHT: bottom right corner; BasicLinkStyleLayout.BOTTOM_LEFT: bottom left corner; or the value BasicLinkStyleLayout.ALL_CORNERS.
setSelfLinkConnectToNodeCenter

Sets whether self-links (that is, links that start and end at the same node) connect towards the node center. This is disabled by default. It has only an effect for the self-link modes BasicLinkStyleLayout.CONNECTED_RECTANGULAR, BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR, BasicLinkStyleLayout.CONNECTED_SQUARE, or BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE. If disabled, the self-link segments incident to the node border are orthogonal to the node border. If enabled, the self-link segments are rotated to point towards the node center.

ParameterTypeDescription
enableBooleanWhether the option is enabled.
setSelfLinkMode

Sets the mode how self-links (that is, links that start and end at the same node) are laid out. Valid values are:

  • BasicLinkStyleLayout.NO_BENDS - no reshape. Self-links are not reshaped with bends and may not be visible after layout.
  • BasicLinkStyleLayout.CONNECTED_RECTANGULAR - rectangular self-links with 3 bends and connection. Self-links are reshaped with 3 bends placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node.
  • BasicLinkStyleLayout.FREE_RECTANGULAR - rectangular self-links with 3 bends without enforced connection. Self-links are reshaped with 3 bends placed at the same position like BasicLinkStyleLayout.CONNECTED_RECTANGULAR. However, the link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point. Since the connection point is not enforced, the link segments in free rectangular mode may not be orthogonal.
  • BasicLinkStyleLayout.CONNECTED_SQUARE - square self-links with 3 bends and connection. Self-links are reshaped with 3 bends placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node.
  • BasicLinkStyleLayout.FREE_SQUARE - square self-links with 3 bends without enforced connection. Self-links are reshaped with 3 bends placed at the same position like BasicLinkStyleLayout.CONNECTED_SQUARE. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. However, the link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point. Since the connection point is not enforced, the link segments in free rectangular mode may not be orthogonal.
  • BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR - narrow rectangular self-links with 3 bends and connection (default). Self-links are reshaped with 3 bends placed in orthogonal style so that the link segments approximately resemble three quarters of a rectangle (the fourth quarter being the node where the self-link is attached). The connection points are placed on the border of the node. For single self-links, this mode has the same effect like BasicLinkStyleLayout.CONNECTED_RECTANGULAR. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from BasicLinkStyleLayout.CONNECTED_RECTANGULAR, as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
  • BasicLinkStyleLayout.NARROW_FREE_RECTANGULAR - narrow rectangular self-links with 3 bends without enforced connection. Self-links are reshaped with 3 bends placed at the same position like BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR. For single self-links, this mode has the same effect like BasicLinkStyleLayout.FREE_RECTANGULAR. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from BasicLinkStyleLayout.FREE_RECTANGULAR, as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point. Since the connection point is not enforced, the link segments in free rectangular mode may not be orthogonal.
  • BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE - narrow square self-links with 3 bends and connection. Self-links are reshaped with 3 bends placed in orthogonal style so that the link segments approximately resemble three quarters of a square (the fourth quarter being the node where the self-link is attached). If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. The connection points are placed on the border of the node. For single self-links, this mode has the same effect like BasicLinkStyleLayout.CONNECTED_SQUARE. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from BasicLinkStyleLayout.CONNECTED_SQUARE, as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node.
  • BasicLinkStyleLayout.NARROW_FREE_SQUARE - narrow square self-links with 3 bends without enforced connection. Self-links are reshaped with 3 bends placed at the same position like BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE. If the self-link is a spline link, the square shape might be more appropriate than a rectangular shape since the spline then may approximately resemble three quarters of a circle. For single self-links, this mode has the same effect like BasicLinkStyleLayout.FREE_SQUARE. If you have multiple self-links at the same node, the self-links are shifted by an offset to avoid overlaps. In this case, this mode differs from BasicLinkStyleLayout.FREE_SQUARE, as the self-link bundle may appear more narrow since the shift offset of the multiple self-links is limited by the size of the end node. The link connection points are not enforced, that is, the nodes and links are free to decide themselves where to place the connection point. Since the connection point is not enforced, the link segments in free square mode may not be orthogonal.
This feature is only useful if the graph contains any self-links. If has only an effect when the link style is not BasicLinkStyleLayout.NO_RESHAPE_STYLE.

ParameterTypeDescription
modeintThe mode for self-links.
setSelfLinkOrientation

Sets the orientation of self-links (that is, links that start and end at the same node). Valid values are:

  • BasicLinkStyleLayout.CLOCK_WISE - clockwise (default).
  • BasicLinkStyleLayout.COUNTER_CLOCK_WISE - counterclockwise.
  • BasicLinkStyleLayout.HORIZONTAL_TO_VERTICAL - horizontal to vertical. Self-links start at the left or right side of the node with a horizontal segment and end at the top or bottom side of the node with a vertical segment.
  • BasicLinkStyleLayout.VERTICAL_TO_HORIZONTAL - vertical to horizontal. Self-links start at the top or bottom side of the node with a vertical segment and end at the left or right side of the node with a horizontal segment.
This feature is only useful if the graph contains any self-links. If has only an effect when the link style is not BasicLinkStyleLayout.NO_RESHAPE_STYLE and the self-link mode is not BasicLinkStyleLayout.NO_BENDS.

ParameterTypeDescription
orientationintThe orientation mode for self-links.
setSelfLinkRelativeAttachPosition

Sets the relative attach position at the node border for self-links (that is, links that start and end at the same node). The x value of the position specifies a point at the top or bottom border of the node, and the y value of the position specifies a point at the left or right border of the node. The relative attach position is expressed as a fraction of the width and height of the node bounding box. Self-links occur at a corner of the node, and the relative position is specified with respect to this corner. For instance, the attach position (0.5, 0.1) specifies the middle of the top or bottom side and a point that is one tenth of the node height away from the corner of the self-link at the left or right side. If the self-link occurs at the bottom right corner, it goes from the middle of the bottom side, to a point at the right side that is 10% away from that corner. The attach position (0.0, 0.0) specifies exactly the corresponding corner. The attach position (1.0, 1.0) specified the, in each direction, opposite corners, that is, if the self-link occurs at the bottom right corner, it goes from the bottom left corner to the top right corner. Such extreme values are perhaps not useful; they are mentioned only to illustrate the meaning of the relative position. The coordinate range for useful values is approximately between 0.1 and 0.5 for the relative position.

If the self-link mode is BasicLinkStyleLayout.CONNECTED_SQUARE, BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE, BasicLinkStyleLayout.FREE_SQUARE, or BasicLinkStyleLayout.NARROW_FREE_SQUARE, then the attach position is only respected at one side and calculate on the other side to form a square.

The real attach position is the sum of the relative attach position and the absolute attach position.

The default value of the relative attach position is (0.5, 0.5).

ParameterTypeDescription
positionPointThe relative attach position for self-links.
setSelfLinkSpacing

Sets the minimal spacing between node border and self-links (that is, links that start and end at the same node). If the self-link mode is BasicLinkStyleLayout.NO_BENDS, the offset has no effect.

If the spacing is negative, the spacing is calculated automatically. This is in particular useful for the self-link modes BasicLinkStyleLayout.CONNECTED_SQUARE and BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE in combination with spline links, to form approximate circle shapes for the self-links.

The default value is 5.

ParameterTypeDescription
spacingNumberThe spacing value.
supportsAllowedTime
Returns Boolean

Indicates that this layout class can stop the layout computation when the user-defined allowed time is exceeded. The result code in the layout report is ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_VALID in this case.

supportsLayoutOfConnectedComponents
Returns Boolean

Indicates that this layout class can cut the attached graph into connected components, apply itself to each connected component separately, and then use the layout instance returned by the method ibm_ilog.graphlayout.GraphLayout.getLayoutOfConnectedComponents() to position the connected components. By default, this layout is an instance of ibm_ilog.graphlayout.grid.GridLayout which can be customized as needed.

supportsLayoutRegion
Returns Boolean

Indicates that this layout class can control the size of the graph drawing to fit (approximately) a user-defined region (a rectangle). By default, this feature is disabled. To enable it, use the method ForceDirectedLayout.setForceFitToLayoutRegion().

supportsLinkConnectionBox
Returns Boolean

Indicates that this layout class can use a link connection box interface to calculate the end points of a link. The link connection box interface is an object that provides the rectangle to which the links are connected for each node and the tangential shift offset at each side for the connection points.

The connection box interface is only used if the link style is straight line. It is used when the option "connect links to node centers" (see BasicLinkStyleLayout.isConnectLinksToNodeCenters()) is enabled. It is used for multilink bundles unless the multilink mode is BasicLinkStyleLayout.NO_BUNDLE or BasicLinkStyleLayout.FREE_ONE_BEND_BUNDLE. It is used for self-links if the self-link mode is BasicLinkStyleLayout.CONNECTED_RECTANGULAR, BasicLinkStyleLayout.NARROW_CONNECTED_RECTANGULAR, BasicLinkStyleLayout.CONNECTED_SQUARE, or BasicLinkStyleLayout.NARROW_CONNECTED_SQUARE. In all other cases, the layout algorithms does not actively place the end points of links, hence it is not used.

When the connection box interface is used, the layout algorithm calculates the virtual center of the end nodes of each link by the link connection box interface and routes the links relative to those centers. The virtual center is defined as the center of the connection box shifted by the average of the tangential "top" and "bottom" offsets in the horizontal direction, and by the average of the tangential "left" and "right" offsets in the vertical direction. For instance, if the tangential offset is 20 at the top side and 10 at all other sides, the average shift offset is (20 + 10)/2 = 15 in the horizontal direction and (10 + 10)/2 = 10 in the vertical direction; hence, the virtual center is at connectionBox.center() + (15, 10).

supportsPercentageComplete
Returns Boolean
Indicates that this layout class can not estimate the percentage of completion during the layout run.
supportsPreserveFixedLinks
Returns Boolean

Indicates that this layout class allows the user to specify fixed links. Fixed links are not reshaped during the layout if the method ibm_ilog.graphlayout.GraphLayout.setPreserveFixedLinks() is called with a true argument.

supportsPreserveFixedNodes
Returns Boolean

Indicates that this layout class allows the user to specify fixed nodes. Fixed nodes are not positioned during the layout if the method ibm_ilog.graphlayout.GraphLayout.setPreserveFixedLinks() is called with a true argument. The base class BasicLinkStyleLayout does not move any nodes anyway, hence specifying nodes as fixed is not necessary. All subclasses of this class however move nodes, and specifying nodes as fixed for a subclass can be useful.

supportsStopImmediately
Returns Boolean

Indicates that this layout class can interrupt the current run of the layout immediately in a controlled way. The result code in the layout report is ibm_ilog.graphlayout.GraphLayoutReport.STOPPED_AND_VALID in this case.