ilog.views.graphlayout.grid

Class IlvGridLayout

java.lang.Object

ilog.views.graphlayout.IlvGraphLayout

ilog.views.graphlayout.grid.IlvGridLayout

public class IlvGridLayout
extends IlvGraphLayout

The main class for the Grid Layout algorithm.

The Grid Layout algorithm has two major modes: grid and row/column. (For details, see the method #setLayoutMode(int).) In grid mode, the layout arranges the nodes of a graph in the cells of a grid (matrix). If a node is too large to fit into one grid cell (with a margin), it occupies multiple cells. The size of the grid cells can be specified using the methods #setHorizontalGridOffset(double) and #setVerticalGridOffset(double). The margins can be specified using the methods #setTopMargin(double), #setBottomMargin(double), #setLeftMargin(double), and #setRightMargin(double).

The following sample drawing shows a layout in the grid mode where the grid size has been specified so that each node fits into one grid cell. (Usually such layouts are more esthetic and appear to be more regular, but a larger area is left empty around the smallest nodes. This is generally the best option when all the nodes have the same size.)

The following sample drawing shows a layout in the grid mode where the grid size has been specified so that some nodes fit into one grid cell and other nodes occupy multiple cells. (Usually such layouts take less space if the nodes have a heterogeneous size.)

The following diagram shows the dimensional parameters of the layout in grid mode.

In row/column mode, the layout arranges the nodes of a graph either by rows or by columns (according to the specified option). The width of the rows is controlled by the width of the layout region parameter. The height of the columns is controlled by the height of the layout region parameter. The margins can be specified using the methods #setTopMargin(double), #setBottomMargin(double), #setLeftMargin(double), and #setRightMargin(double). The minimum horizontal distance between nodes is equal to the sum of the left and right margins. The minimum vertical distance between nodes is equal to the sum of the top and bottom margins.

For graphs with nodes of heterogeneous size, the row/column mode often allows a more compact layout than the grid mode.

The following sample drawing shows a layout in the row mode.

The following sample drawing shows a layout in the column mode.

The following diagram shows the dimensional parameters of the layout in row mode (the parameters for the column mode are analogous).

The algorithm is primarily designed for graphs without (visible) links between the nodes. If links exist, they are ignored by the Grid layout.

Several alignment options are provided (see #setGlobalHorizontalAlignment(int) and #setGlobalVerticalAlignment(int)). The alignment can be specified individually for each node (see #setHorizontalAlignment(Object, int) and #setVerticalAlignment(Object, int)).

An incremental mode is provided (see #setIncrementalMode(boolean)). If the incremental mode is enabled, the stability of the layout is preserved as much as possible when new nodes are added, existing ones removed, or node sizes modified. This means that the nodes are placed at the same location, or in the same order, as in the previous layout whenever possible. In this mode, the layout algorithm processes the changes incrementally rather than redoing the entire layout for every change.

Nodes that the layout algorithm is not allowed to move can be specified using the method #setFixed(Object, boolean). (See also #setPreserveFixedNodes(boolean).) In grid mode, nonfixed nodes are placed in such a way that they do not overlap the grid cells occupied by other fixed or nonfixed nodes. In row/column mode, nonfixed nodes are placed in such a way that they do not overlap fixed or nonfixed nodes. Of course, fixed nodes can overlap other fixed nodes.

The layout algorithm can take into account a different node size than the size corresponding to the bounding box of the node. Using #setNodeBoxInterface(IlvNodeBoxInterface), you can specify an object that provides the box that has to be taken into account for each node. The following diagram shows the dimensional parameters of the layout in grid mode (the row/column case mode is analogous) when a node box that is different from the bounding box of the node is used:

CSS example:

SDM {
GraphLayout : true;
}

GraphLayout {
graphLayout : @#layout;
// optional settings for the graph layout renderer
}

Subobject#layout {
class : "ilog.views.graphlayout.grid.IlvGridLayout";
allowedTime : "3";
bottomMargin : "3.0";
coordinatesMode : "MANAGER_COORDINATES";
globalHorizontalAlignment : "CENTER";
globalVerticalAlignment : "CENTER";
horizontalGridOffset : "3.0";
incrementalMode : "false";
layoutMode : "TILE_TO_GRID_FIXED_WIDTH";
leftMargin : "3.0";
maxNumberOfNodesPerRowOrColumn : "2";
minBusyTime : "3";
nodeComparator : "@#nodeComparator";
rightMargin : "3.0";
topMargin : "3.0";
verticalGridOffset : "3.0";
}

Subobject#nodeComparator {
class : "ilog.views.sdm.renderer.graphlayout.IlvSDMObjectComparator";
textualSortCriteria : "data,name,ascendent;data,value,descendent;comparator,DESCENDING_HEIGHT,ascending";
}

CSS specification of per-node and per-link layout parameters:

The following table lists the per-object rendering properties of the GraphLayout renderer:

Property	Type	Default	Description
GraphLayout	IlvGraphLayout	null	Lets you define a different graph layout algorithm for each subgraph. If one is not specified, the same algorithm is applied recursively to all subgraphs.
LayoutFixed	String	false	Deprecated, replaced by Fixed.
Fixed	String	false	Lets you specify that the node or link must not be moved or reshaped by the layout algorithm.
LayoutGroup	String	null	Lets you apply the algorithm to different groups of objects, one group after the other.
LayoutIgnored	boolean	false	If true, the object is ignored by the layout.

The per-node and per-link layout parameters are specified in the style sheet through the CSS rules for nodes and links, not through the CSS rule for graph layout. For instance:

link.tag {
LinkStyle : "ORTHOGONAL_STYLE";
}

Note that the names of the node and link layout parameters use an initial capital, unlike the regular properties. See also the documentation of the class IlvGraphLayoutRenderer.

Property Summary

Properties

Modifier and Type	Property and Description
long	allowedTime Sets the upper limit for the duration of the layout algorithm.
double	bottomMargin Sets the bottom margin parameter.
java.lang.String	class Default constructor.
int	coordinatesMode Sets the coordinates mode to be used during layout.
int	globalHorizontalAlignment Sets the global horizontal alignment style.
int	globalVerticalAlignment Sets the global vertical alignment style.
double	horizontalGridOffset Sets the spacing of the grid lines on the horizontal axis.
boolean	incrementalMode Sets the incremental mode.
int	layoutMode Sets the layout mode.
double	leftMargin Sets the left margin parameter.
int	maxNumberOfNodesPerRowOrColumn Sets the maximum number of nodes per row or per column.
long	minBusyTime Sets the minimal time that the layout algorithm can be busy.
java.util.Comparator	nodeComparator Sets the comparator used for sorting the nodes.
double	rightMargin Sets the right margin parameter.
double	topMargin Sets the top margin parameter.
double	verticalGridOffset Sets the spacing of the grid lines on the vertical axis.

Method Summary

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Property Detail

class

public java.lang.String class

Default constructor.

CSS example: class : "ilog.views.graphlayout.grid.IlvGridLayout";

allowedTime

public long allowedTime

Sets the upper limit for the duration of the layout algorithm.

When an iterative layout algorithm is used, the iterations can be stopped when this time is exceeded. Noniterative algorithms can also use this parameter as an upper limit for the computation time. The default value is normally 32000 (32 seconds). Subclasses that support this feature can use a different default value depending on their particular behavior. Layout algorithms that are stopped in this way set the result code of the layout report either to IlvGraphLayoutReport#STOPPED_AND_VALID or to IlvGraphLayoutReport#STOPPED_AND_INVALID.

When the connected components of disconnected graphs are laid out separately (see #supportsLayoutOfConnectedComponents()), the specified allowed time is considered as the total time for the layout of all the connected components plus the time for the connected components layout.

Note that the layout algorithm may not obey exactly the allowed time specification.

Note for implementers of layout algorithms: the method #performLayout(boolean, boolean, boolean) does NOT automatically stop the layout when the allowed time is exceeded. It is the sole responsibility of the implementation of the method #layout(boolean) to do this.

A RuntimeException is thrown if the layout does not support this mechanism.

CSS example: allowedTime : "3";

bottomMargin

public double bottomMargin

Sets the bottom margin parameter.

If the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, the bottom margin is the minimum distance between the bottom border of a node (or its user-specified box - see #setNodeBoxInterface(IlvNodeBoxInterface)) and the bottom border of the grid cell.

If the layout mode is #TILE_TO_ROWS or #TILE_TO_COLUMNS, the minimum vertical distance between two nodes (or their user-specified boxes) is the sum of the top and bottom margins.

The default value is 5.

CSS example: bottomMargin : "3.0";

coordinatesMode

public int coordinatesMode

Sets the coordinates mode to be used during layout.

Valid values are:

• ilog.views.graphlayout.IlvGraphLayout#MANAGER_COORDINATES - The geometry of the graph is computed using the coordinate space of the manager (that is, the attached IlvGrapher) without applying any transformation.

  This mode should be used if you visualize the graph at zoom level 1, or you do not visualize it at all, or the graph contains only fully zoomable objects. In all these cases there is no need to take the transformer into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates.

• ilog.views.graphlayout.IlvGraphLayout#VIEW_COORDINATES - The geometry of the graph is computed in the coordinate space of the manager view. More exactly, all the coordinates are transformed using the current reference transformer.

  This mode should be used if you want the dimensional parameters of the layout algorithms to be considered as being specified in manager view coordinates.

• ilog.views.graphlayout.IlvGraphLayout#INVERSE_VIEW_COORDINATES - The geometry of the graph is computed using the coordinate space of the manager view and then applying the inverse transformation. This mode is equivalent to the "manager coordinates" mode if the geometry of the graphic objects strictly obeys the transformer. (A small difference may exist because of the limited precision of the computations.)

  On the contrary, if some graphic objects are either nonzoomable (see IlvGraphic#zoomable) or semizoomable (for example, links with a maximum line width), this mode gives different results than the manager coordinates mode. These results are optimal if the graph is visualized using the same transformer as the one taken into account during the layout.

  Note that in this mode the dimensional parameters of the layout algorithms are considered as being specified in manager coordinates.

The default value is IlvGraphLayout#INVERSE_VIEW_COORDINATES.

This option is useful only if the attached graph model is an IlvGrapherAdapter (or a subclass). Otherwise, it has no effect. Note: the coordinates mode of the layout is used only while this layout is running. If layout is not running, operations on the grapher adapter use the coordinates mode that was set on the grapher adapter directly (see IlvGrapherAdapter#setCoordinatesMode).

CSS example: coordinatesMode : "MANAGER_COORDINATES";

Allowed values:

MANAGER_COORDINATES

VIEW_COORDINATES

INVERSE_VIEW_COORDINATES

globalHorizontalAlignment

public int globalHorizontalAlignment

Sets the global horizontal alignment style. This method controls the horizontal alignment of nodes either inside their grid cell if the layout mode (see #setLayoutMode(int)) is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, or inside the columns if the layout mode is #TILE_TO_COLUMNS. This parameter is not used if the layout mode (see #setLayoutMode(int)) is #TILE_TO_ROWS.

Valid values are:

• #CENTER - the node is centered in its grid cell or column.
• #LEFT - the node is aligned to the left border of the cell or column.
• #RIGHT - the node is aligned to the left border of the cell or column.
• #MIXED - each node can have a different alignment option. In this case, the horizontal alignment of each individual node can be set by the method #setHorizontalAlignment(Object, int) so that different alignments can occur in the same layout.

The default value is #CENTER.

CSS example: globalHorizontalAlignment : "CENTER";

Allowed values:

CENTER

LEFT

RIGHT

MIXED

globalVerticalAlignment

public int globalVerticalAlignment

Sets the global vertical alignment style. This method controls the vertical alignment of nodes either inside their grid cell if the layout mode (see #setLayoutMode(int)) is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, or inside the rows if the layout mode is #TILE_TO_ROWS. This parameter is not used if the layout mode (see #setLayoutMode(int)) is #TILE_TO_COLUMNS.

Valid values are:

• #CENTER - the node is centered in its grid cell or column.
• #TOP - the node is aligned to the top border of the cell or column.
• #BOTTOM - the node is aligned to the bottom border of the cell or column.
• #MIXED - each node can have a different alignment option. In this case, the vertical alignment of each individual node can be set by the method #setVerticalAlignment(Object, int) so that different alignments can occur in the same layout.

The default value is #CENTER.

CSS example: globalVerticalAlignment : "CENTER";

Allowed values:

CENTER

TOP

BOTTOM

MIXED

horizontalGridOffset

public double horizontalGridOffset

Sets the spacing of the grid lines on the horizontal axis.

The default value is 40.

This parameter is not used if the layout mode (see #setLayoutMode(int)) is #TILE_TO_ROWS or #TILE_TO_COLUMNS.

CSS example: horizontalGridOffset : "3.0";

incrementalMode

public boolean incrementalMode

Sets the incremental mode.

If the incremental mode is enabled, the stability of the layout is preserved as much as possible when new nodes are added, existing ones removed, or node sizes modified. This means that the nodes are placed at the same location or in the same order as in the previous layout whenever possible. In this mode, the layout algorithm processes the changes incrementally rather than redoing the entire layout for every change.

To preserve the stability, the incremental mode can keep some regions free. Therefore, the total area of the layout can be larger than when nonincremental mode is used.

Note that the layout is redone from scratch after a change in one of the following parameters:

• layout region
• grid offset
• layout mode
• margins

The default value is false (disabled).

CSS example: incrementalMode : "false";

layoutMode

public int layoutMode

Sets the layout mode. Valid values are:

• #TILE_TO_GRID_FIXED_WIDTH - The nodes are placed in the cells of a grid (matrix) that has a fixed maximum number of columns. This number is equal to the width of the layout region parameter divided by the horizontal grid offset (see #setHorizontalGridOffset(double)).
• #TILE_TO_GRID_FIXED_HEIGHT - The nodes are placed in the cells of a grid (matrix) that has a fixed maximum number of rows. This number is equal to the height of the layout region parameter divided by the vertical grid offset (see #setVerticalGridOffset(double)).
• #TILE_TO_ROWS - The nodes are placed in rows. The maximum width of the rows is equal to the width of the layout region parameter. The height of each row is the maximum height of the nodes contained in the row (plus margins).
• #TILE_TO_COLUMNS - The nodes are placed in columns. The maximum height of the columns is equal to the height of the layout region parameter. The width of each column is the maximum width of the nodes contained in the column (plus margins).

The default value is #TILE_TO_GRID_FIXED_WIDTH.

CSS example: layoutMode : "TILE_TO_GRID_FIXED_WIDTH";

Allowed values:
TILE_TO_GRID_FIXED_WIDTH		Tile to Grid (fixed width)
TILE_TO_GRID_FIXED_HEIGHT		Tile to Grid (fixed height)
TILE_TO_ROWS
TILE_TO_COLUMNS

leftMargin

public double leftMargin

Sets the left margin parameter.

If the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, the left margin is the minimum distance between the left border of a node (or its user-specified box - see #setNodeBoxInterface(IlvNodeBoxInterface)) and the left border of the grid cell.

If the layout mode is #TILE_TO_ROWS or #TILE_TO_COLUMNS, the minimum horizontal distance between two nodes (or their user-specified boxes) is the sum of the left and right margins.

The default value is 5.

CSS example: leftMargin : "3.0";

maxNumberOfNodesPerRowOrColumn

public int maxNumberOfNodesPerRowOrColumn

Sets the maximum number of nodes per row or per column.

In #TILE_TO_ROWS mode, the number is the maximum number of nodes per row. In #TILE_TO_COLUMNS mode, the number is the maximum number of nodes per column.

The layout places as many nodes on each row or column as possible given the size of the nodes, the dimensional parameters (layout region and margins) and the specified maximum number of nodes per row or column.

The minimum value is 1. The default value is Integer.MAX_VALUE , that is, the number of nodes placed in each row or column is bounded only by the size of the nodes and the dimensional parameters. The parameter has no effect if the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT.

CSS example: maxNumberOfNodesPerRowOrColumn : "2";

minBusyTime

public long minBusyTime

Sets the minimal time that the layout algorithm can be busy. This is the time between two calls of #layoutStepPerformed() when the method #callLayoutStepPerformedIfNeeded() is used.

The objective is to avoid the overhead of #layoutStepPerformed() becoming too high if the method is called too often. Internal routines of layout algorithms usually call #callLayoutStepPerformedIfNeeded(), which calls #layoutStepPerformed() if the time since the last call was at least the minimal busy time.

The default value is 50 (milliseconds).

CSS example: minBusyTime : "3";

nodeComparator

public java.util.Comparator nodeComparator

Sets the comparator used for sorting the nodes. The valid values are the following:

• #AUTOMATIC_ORDERING - The algorithm is free to choose an order aimed at reducing the total area occupied by the layout.
• #NO_ORDERING - No ordering is performed.
• #DESCENDING_HEIGHT - The nodes are ordered in descending order of height.
• #ASCENDING_HEIGHT - The nodes are ordered in ascending order of height.
• #DESCENDING_WIDTH - The nodes are ordered in descending order of width.
• #ASCENDING_WIDTH - The nodes are ordered in ascending order of width.
• #DESCENDING_AREA - The nodes are ordered in descending order of area.
• #ASCENDING_AREA - The nodes are ordered in ascending order of area.
• #ASCENDING_INDEX - The nodes are ordered in ascending order of index value (see #setIndex(Object, int)).
• #DESCENDING_INDEX - The nodes are ordered in descending order of index value (see #setIndex(Object, int)).
• null - The nodes are ordered in an arbitrary way.
• Any other implementation of the java.util.Comparator interface - the nodes are ordered according to this custom comparator .

The default value is #AUTOMATIC_ORDERING.

The ordering of the nodes starts at the upper-left corner.

In incremental mode (see #setIncrementalMode(boolean)) or when nodes are fixed (see #setFixed(Object, boolean)) the order of the nodes is not guaranteed to obey the comparator, since this specification competes with the other constraints.

If the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, the order options are applied only for nodes whose size (including margins) is smaller than the grid cell size (see #setHorizontalGridOffset(double) and #setVerticalGridOffset(double)).

CSS example:

nodeComparator : "@#nodeComparator";

Subobject#nodeComparator {
class : "ilog.views.sdm.renderer.graphlayout.IlvSDMObjectComparator";
textualSortCriteria : "data,name,ascendent;data,value,descendent;comparator,DESCENDING_HEIGHT,ascending";
}

See also the documentation of the class IlvSDMObjectComparator.

rightMargin

public double rightMargin

Sets the right margin parameter.

If the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, the right margin is the minimum distance between the right border of a node (or its user-specified box - see #setNodeBoxInterface(IlvNodeBoxInterface)) and the right border of the grid cell.

If the layout mode is #TILE_TO_ROWS or #TILE_TO_COLUMNS, the minimum horizontal distance between two nodes (or their user-specified boxes) is the sum of the left and right margins.

The default value is 5.

CSS example: rightMargin : "3.0";

topMargin

public double topMargin

Sets the top margin parameter.

If the layout mode is #TILE_TO_GRID_FIXED_WIDTH or #TILE_TO_GRID_FIXED_HEIGHT, the top margin is the minimum distance between the top border of a node (or its user-specified box - see #setNodeBoxInterface(IlvNodeBoxInterface)) and the top border of the grid cell.

If the layout mode is #TILE_TO_ROWS or #TILE_TO_COLUMNS, the minimum vertical distance between two nodes (or their user-specified boxes) is the sum of the top and bottom margins.

The default value is 5.

CSS example: topMargin : "3.0";

verticalGridOffset

public double verticalGridOffset

Sets the spacing of the grid lines on the vertical axis.

The default value is 40.

This parameter is not used if the layout mode (see #setLayoutMode(int)) is #TILE_TO_ROWS or #TILE_TO_COLUMNS.

CSS example: verticalGridOffset : "3.0";