Specific parameters of the GL

Order parameter (GL)

The order parameter specifies how to arrange the nodes.
Example of specifying node placement iterations and allowed time (GL algorithm)
To specify the ordering option for the nodes:
Use the method:
gridLayout.setNodeComparator(ibm_ilog.graphlayout.grid.GridLayout.DESCENDING_HEIGHT); 
The order parameter specifies how to arrange the nodes.
The valid values for comparator are:
  • ibm_ilog.graphlayout.grid.GridLayout.AUTOMATIC_ORDERING
    The algorithm is free to choose the order in such a way that it tries to reduce the total area occupied by the layout.
  • ibm_ilog.graphlayout.grid.GridLayout.NO_ORDERING
    No ordering is performed.
  • ibm_ilog.graphlayout.grid.GridLayout.DESCENDING_HEIGHT
    The nodes are ordered in the descending order of their height.
  • ibm_ilog.graphlayout.grid.GridLayout.ASCENDING_HEIGHT
    The nodes are ordered in the ascending order of their height.
  • ibm_ilog.graphlayout.grid.GridLayout.DESCENDING_WIDTH
    The nodes are ordered in the descending order of their width.
  • ibm_ilog.graphlayout.grid.GridLayout.ASCENDING_WIDTH
    The nodes are ordered in the ascending order of their width.
  • ibm_ilog.graphlayout.grid.GridLayout.DESCENDING_AREA
    The nodes are ordered in the descending order of their area.
  • ibm_ilog.graphlayout.grid.GridLayout.ASCENDING_AREA
    The nodes are ordered in the ascending order of their area.
  • ibm_ilog.graphlayout.grid.GridLayout.ASCENDING_INDEX
    The nodes are ordered in the ascending order of their index (seesetIndex).
  • ibm_ilog.graphlayout.grid.GridLayout.DESCENDING_INDEX
    The nodes are ordered in the descending order of their index (see setIndex).
  • null
    The nodes are ordered in an arbitrary way.
  • Any object with a compare property whose value must be a function.
    The nodes are ordered according to this custom comparator.
  • The compare function must have the following signature:
    compareFunction (A, B)
    The comparison function compares two arguments. For example: Given two elements A and B, the compareFunction returns one of the following values:
    • -1
      The function returns A before B in the sorted sequence.
    • 0
      A equals B.
    • 1
      The function returns A after B in the sorted sequence.
The default is ibm_ilog.graphlayout.grid.GridLayout.AUTOMATIC_ORDERING.
In incremental mode (see setIncrementalMode) and with fixed nodes (see setFixed), the order of the nodes is not completely preserved.
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 and setVerticalGridOffset).

Layout modes (GL)

The Grid Layout algorithm has four layout modes.
Example of selecting a layout mode (GL algorithm)
To select a layout mode:
Use the method:
gridLayout.setLayoutMode(ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_GRID_FIXED_HEIGHT);  
The valid values for mode are:
  • ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_GRID_FIXED_WIDTH (the default).
    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.
  • ibm_ilog.graphlayout.grid.GridLayout.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.
  • ibm_ilog.graphlayout.grid.GridLayout.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 the row is the maximum height of the nodes contained in the row (plus margins).
  • ibm_ilog.graphlayout.grid.GridLayout.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 the column is the maximum width of the nodes contained in the column (plus margins).

Alignment parameters (GL)

Global alignment parameters

The alignment options control how a node is placed over its grid cell or over its row or column (depending on the layout mode). The alignment can be set globally, in which case all nodes are aligned in the same way, or locally on each node, with the result that different alignments occur in the same drawing.
Example of setting global alignment (GL algorithm)
To set the global alignment:
Use the following methods:
gridLayout.setGlobalHorizontalAlignment(ibm_ilog.graphlayout.grid.GridLayout.LEFT);
gridLayout.setGlobalVerticalAlignment(ibm_ilog.graphlayout.grid.GridLayout.TOP);
The valid values for the alignment parameter are:
  • ibm_ilog.graphlayout.grid.GridLayout.CENTER (the default)
    The node is horizontally and vertically centered over its grid cell or row or column.
  • ibm_ilog.graphlayout.grid.GridLayout.TOP
    The node is vertically aligned on the top of its cell or row. Not used if the layout mode is TILE_TO_COLUMNS.
  • ibm_ilog.graphlayout.grid.GridLayout.BOTTOM
    The node is vertically aligned on the bottom of its grid cell or row. Not used if the layout mode is TILE_TO_COLUMNS.
  • ibm_ilog.graphlayout.grid.GridLayout.LEFT
    The node is horizontally aligned on the left of its grid cell or column. Not used if the layout mode is TILE_TO_ROWS.
  • ibm_ilog.graphlayout.grid.GridLayout.RIGHT
    The node is horizontally aligned on the right of its grid cell or column. Not used if the layout mode is TILE_TO_ROWS.
  • ibm_ilog.graphlayout.grid.GridLayout.MIXED
    Each node can have a different alignment. The alignment of each individual node can be set with the result that different alignments can occur in the same graph.

Alignment of individual nodes

All nodes have the same alignment unless the global alignment is set to ibm_ilog.graphlayout.grid.GridLayout.MIXED. Only when the global alignment is set to mixed can each node have an individual alignment style.
Example of setting alignment of individual nodes (GL algorithm)
To set and retrieve the alignment of an individual node:
Use the following methods:
setHorizontalAlignment(node, alignment);  
setVerticalAlignment(node, alignment);   
getHorizontalAlignment(node);   
getVerticalAlignment(node);   
The valid values for the alignment parameter are:
  • ibm_ilog.graphlayout.grid.GridLayout.CENTER (the default)
  • ibm_ilog.graphlayout.grid.GridLayout.TOP
  • ibm_ilog.graphlayout.grid.GridLayout.BOTTOM
  • ibm_ilog.graphlayout.grid.GridLayout.LEFT
  • ibm_ilog.graphlayout.grid.GridLayout.RIGHT

Maximum number of nodes per row or column (GL)

By default, in ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_ROWS or ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_COLUMNS mode, the layout places as many nodes on each row or column as possible given the size of the nodes and the dimensional parameters (layout region and margins). If needed, the layout can additionally respect a specified maximum number of nodes per row or column.
Example of specifying the maximum number of nodes per row or column (GL algorithm)
To set the maximum number of nodes per row or column:
Use the method:
gridLayout.setMaxNumberOfNodesPerRowOrColumn(5);  
The default value is int.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 specified value must be at least 1. The parameter has no effect if the layout mode is ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_GRID_FIXED_WIDTH or ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_GRID_FIXED_HEIGHT.

Incremental mode (GL)

The Grid Layout algorithm normally places all the nodes from scratch. If the graph incrementally changes because you add, remove, or resize nodes, the subsequent layout can differ considerably from the previous layout. To avoid this effect and to help the user to retain a mental map of the graph, the algorithm has an incremental mode. In incremental mode, the layout tries to place the nodes at the same location or in the same order as in the previous layout whenever it is possible.
Example of enabling the incremental mode (GL algorithm)
To enable the incremental mode:
Call the method setIncrementalMode as follows:
gridLayout.setIncrementalMode(true); 
Note
To preserve stability, the incremental mode can keep some regions free. Therefore, the total area of the layout can be larger than in nonincremental mode, and, in general, the layout cannot look as nice as in nonincremental mode.

Dimensional parameters (GL)

Dimensional parameters for the grid mode of the Grid Layout algorithm and Dimensional parameters for the row-and-column mode of the Grid Layout algorithm illustrate the dimensional parameters used in the Grid Layout algorithm. These parameters are explained in the sections that follow.
Diagram
illustrating the margin and grid offset parameters of Grid Layout
in grid mode
Dimensional parameters for the grid mode of the Grid Layout algorithm
Diagram
illustrating the margin and layout region parameters of Grid Layout
in row and column mode
Dimensional parameters for the row-and-column mode of the Grid Layout algorithm

Grid offset (GL)

The grid offset parameters control the spacing between grid lines. It is taken into account only by the grid mode (layout modes TILE_TO_GRID_FIXED_WIDTH and TILE_TO_GRID_FIXED_HEIGHT).
Example of setting grid offset (GL algorithm)
To set the horizontal and vertical grid offset:
Use the methods:
gridLayout.setHorizontalGridOffset(50);
gridLayout.setVerticalGridOffset(50);  
The grid offset is the critical parameter for the grid mode. If the grid offset is larger than the size of the nodes (plus margins), an empty space is left around the node. If the grid offset is smaller than the size of the nodes (plus margins), the node must be placed on more than one grid cell. The best choice for the grid offsets depends on the application. It can be computed according to either the maximum size of the nodes (plus margins) or the medium size, and so on. If all the nodes have a similar size, the choice is straightforward.

Margins (GL)

The margins control the space around each node that the layout algorithm keeps empty.
Example of specifying margins (GL algorithm)
To set the margins:
Use the methods:
gridLayout.setTopMargin(10);
gridLayout.setBottomMargin(10);
gridLayout.setLeftMargin(5);
gridLayout.setRightMargin(5);  
The meaning of the margin parameters is not the same for the grid modes as for the row/column modes:
The default value for all the margin parameters is 5.