y.layout.grid
Class PartitionGrid

java.lang.Object
  y.layout.grid.PartitionGrid

public class PartitionGrid
extends java.lang.Object

This class represents a partition grid that partitions the drawing area into rectangular partition cells. Such a structure allows, for example, to model vertical/horizontal swimlanes which are often used in flow diagrams to separate logical units.

The grid consists of rows and columns that are created using the corresponding constructors of this class or methods addRow() and addColumn(). The PartitionGrid object has to be registered with the graph using the DataProvider key PARTITION_GRID_DPKEY.

Each node can be assigned to a PartitionCellId which represents a set of partition cells. The mapping has to be registered with the graph using DataProvider key PARTITION_CELL_DPKEY. Simple partition cell identifiers which represent a single partition cell, i.e., a row/column pair, can be created using method createCellId(RowDescriptor, ColumnDescriptor) or createCellId(int, int).

Nodes can also be mapped to a partition cell identifier that represents a multi-cell, i.e., a cell spanning multiple columns and rows. Please note, however, that multi-cells are not allowed to overlap each other. This means that the user has to ensure that each partition cell (row/column pair) is associated with at most one partition cell identifier. The multi-cell identifier can be created using methods createCellSpanId(RowDescriptor, ColumnDescriptor, RowDescriptor, ColumnDescriptor), createCellSpanId(int, int, int, int), createCellSpanId(Collection, Collection), createColumnSpanId(int), and createRowSpanId(int).

Sample output of a layout algorithm with a partition grid

The partition cell identifier of a group node is not inherited by its non-group descendant. Hence, each non-group descendant has to be manually assigned to a partition cell identifier. In addition, a group node mapped to a column/row span partition cell identifier represents the associated column/row. Thus, its boundary corresponds to that of the column/row and edges incident to such a group node are not considered during the layout. Since the boundary of a group node always encompasses all of its children, don't assign a partition cell identifier to layout the group as normal.

If at least one node is mapped to a multi-cell, enabling option setColumnOrderOptimizationEnabled(boolean) or setRowOrderOptimizationEnabled(boolean) has no effect.

Field Summary

static java.lang.Object	PARTITION_CELL_DPKEY A DataProvider key for storing a set of partition cells for each node Each node is placed inside the columns/rows defined by the corresponding PartitionCellId identifier.
static java.lang.Object	PARTITION_GRID_DPKEY A DataProvider key for storing the partition grid structure If the DataProvider contains a partition grid structure, this structure will be considered during layout (provided that the layout algorithm supports such constraints).

Constructor Summary

PartitionGrid()
Creates a new empty instance of PartitionGrid.

PartitionGrid(int rowCount, int columnCount)
Creates an instance of PartitionGrid with the given number of rows and columns.

PartitionGrid(int rowCount, int columnCount, double rowInsets, double columnInsets, double minRowSize, double minColumnSize)
Creates an instance of PartitionGrid with the given number of rows and columns as well as with given insets and minimum sizes.

Method Summary

ColumnDescriptor	addColumn() Adds a new column to the PartitionGrid instance.
RowDescriptor	addRow() Adds a new row to the PartitionGrid instance.
PartitionCellId	createCellId(int rowIndex, int columnIndex) Creates a partition cell identifier that represents the cell defined by the given column and row index.
PartitionCellId	createCellId(RowDescriptor rd, ColumnDescriptor cd) Creates a partition cell identifier that represents the cell defined by the given column and row.
PartitionCellId	createCellSpanId(java.util.Collection rowList, java.util.Collection columnList) Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.
PartitionCellId	createCellSpanId(int fromRowIndex, int fromColIndex, int toRowIndex, int toColIndex) Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.
PartitionCellId	createCellSpanId(RowDescriptor fromRow, ColumnDescriptor fromCol, RowDescriptor toRow, ColumnDescriptor toCol) Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.
PartitionCellId	createColumnSpanId(int columnIndex) Creates a partition cell identifier that represents a cell spanning a whole column.
PartitionCellId	createRowSpanId(int rowIndex) Creates a partition cell identifier that represents a cell spanning a whole row.
void	finalizeOrientationChange(OrientationLayouter orientationLayouter, OrientationLayouter.Transformer transformer) Finalizes the orientation changes and is called at the end of the OrientationLayouter stage.
ColumnDescriptor	getColumn(int index) Returns the column with the given index.
YList	getColumns() Returns the columns of the partition grid.
static PartitionGrid	getPartitionGrid(Graph graph) Returns the PartitionGrid instance associated with the given graph.
RowDescriptor	getRow(int index) Returns the row with the given index.
YList	getRows() Returns the list of rows of the partition grid.
boolean	isColumnOrderOptimizationEnabled() Returns whether or not the order of the columns should be chosen automatically to minimize edge lengths.
boolean	isRowOrderOptimizationEnabled() Returns whether or not the order of the rows should be chosen automatically to minimize edge lengths.
void	optimizeColumnOrder(Graph g) Optimizes the order of the columns of the PartitionGrid for the given graph.
void	optimizeRowOrder(Graph g) Optimizes the order of the rows of the PartitionGrid for the given graph.
void	prepareOrientationChange(OrientationLayouter orientationLayouter, OrientationLayouter.Transformer transformer) Prepares for the orientation changes and is called at the beginning of the OrientationLayouter stage.
void	setColumnOrderOptimizationEnabled(boolean enabled) Specifies whether or not the order of the columns should be chosen automatically to minimize edge lengths.
void	setRowOrderOptimizationEnabled(boolean enabled) Specifies whether or not the order of the rows should be chosen automatically to minimize edge lengths.

Methods inherited from class java.lang.Object

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

Field Detail

PARTITION_GRID_DPKEY

public static final java.lang.Object PARTITION_GRID_DPKEY

A DataProvider key for storing the partition grid structure

If the DataProvider contains a partition grid structure, this structure will be considered during layout (provided that the layout algorithm supports such constraints).

It is strongly recommended to create this DataProvider with method DataProviders.createConstantDataProvider(Object) using the PartitionGrid instance as parameter.

PARTITION_CELL_DPKEY

public static final java.lang.Object PARTITION_CELL_DPKEY

A DataProvider key for storing a set of partition cells for each node

Each node is placed inside the columns/rows defined by the corresponding PartitionCellId identifier. Instances can be shared among multiple nodes, but don't have to be shared.

Multi-cell identifiers (i.e., an identifier that represents multiple columns/rows) are not allowed to overlap each other.

See Also:

PartitionCellId

Constructor Detail

PartitionGrid

public PartitionGrid()

Creates a new empty instance of PartitionGrid.

PartitionGrid

public PartitionGrid(int rowCount,
                     int columnCount)

Creates an instance of PartitionGrid with the given number of rows and columns.

Parameters:

rowCount - the number of rows

columnCount - the number of columns

PartitionGrid

public PartitionGrid(int rowCount,
                     int columnCount,
                     double rowInsets,
                     double columnInsets,
                     double minRowSize,
                     double minColumnSize)

Creates an instance of PartitionGrid with the given number of rows and columns as well as with given insets and minimum sizes.

Parameters:

rowCount - the number of rows

columnCount - the number of columns

rowInsets - the top and bottom insets of the rows

columnInsets - the left and right insets of the columns

minRowSize - the minimum row height

minColumnSize - the minimum column width

Method Detail

isColumnOrderOptimizationEnabled

public boolean isColumnOrderOptimizationEnabled()

Returns whether or not the order of the columns should be chosen automatically to minimize edge lengths.

For all columns where ColumnDescriptor.setIndexFixed(boolean) is set to true, the relative ordering given by the indices is preserved. The remaining columns may be sorted again so that the overall edge lengths are minimized.

If at least one node is mapped to a multi-cell (i.e., a cell spanning multiple columns/rows), enabling this option has no effect.

Returns:

true if the order is chosen automatically, false otherwise

See Also:

setColumnOrderOptimizationEnabled(boolean)

setColumnOrderOptimizationEnabled

public void setColumnOrderOptimizationEnabled(boolean enabled)

Specifies whether or not the order of the columns should be chosen automatically to minimize edge lengths.

For all columns where ColumnDescriptor.setIndexFixed(boolean) is set to true, the relative ordering given by the indices is preserved. The remaining columns may be sorted again so that the overall edge lengths are minimized.

If at least one node is mapped to a multi-cell (i.e., a cell spanning multiple columns/rows), enabling this option has no effect.

Default Value:

The default value is true.

Parameters:

enabled - true if the order should be chosen automatically, false otherwise

Sample Graphs:

false

true

isRowOrderOptimizationEnabled

public boolean isRowOrderOptimizationEnabled()

Returns whether or not the order of the rows should be chosen automatically to minimize edge lengths.

For all rows where RowDescriptor.setIndexFixed(boolean) is set to true, the relative ordering given by the indices is preserved. The remaining rows may be sorted again so that the overall edge lengths are minimized.

If at least one node is mapped to a multi-cell (i.e., a cell spanning multiple columns/rows), enabling this option has no effect.

Returns:

true if the order is chosen automatically, false otherwise

See Also:

setRowOrderOptimizationEnabled(boolean)

setRowOrderOptimizationEnabled

public void setRowOrderOptimizationEnabled(boolean enabled)

Specifies whether or not the order of the rows should be chosen automatically to minimize edge lengths.

For all rows where RowDescriptor.setIndexFixed(boolean) is set to true, the relative ordering given by the indices is preserved. The remaining rows may be sorted again so that the overall edge lengths are minimized.

If at least one node is mapped to a multi-cell (i.e., a cell spanning multiple columns/rows), enabling this option has no effect.

Default Value:

The default value is true.

Parameters:

enabled - true if the order should be chosen automatically, false otherwise

Sample Graphs:

false

true

createColumnSpanId

public PartitionCellId createColumnSpanId(int columnIndex)

Creates a partition cell identifier that represents a cell spanning a whole column.

A group node mapped to such a partition cell identifier represents the column, i.e., its enclosing boundary corresponds to that of the column. The boundary does not depend on the partition cells associated with the group's descendants. Hence, each non-group descendant has to be manually assigned to one of the partition cells. Furthermore, edges incident to such a group node are not considered during the layout.

Parameters:

columnIndex - the column index of the column defining the cell

Returns:

a PartitionCellId instance

createCellSpanId

public PartitionCellId createCellSpanId(int fromRowIndex,
                                        int fromColIndex,
                                        int toRowIndex,
                                        int toColIndex)

Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.

The partition cell identifier represents all cells defined by a row with index between fromRowIndex and toRowIndex (both including) and a column with index between fromColIndex and toColIndex (both including).

A group node mapped to such a partition cell identifier represents the multi-cell, i.e., its boundary corresponds to the smallest rectangle containing all partition cells specified by the partition cell identifier. The boundary does not depend on the partition cells associated with the group's descendants. Hence, each non-group descendant has to be manually assigned to one of the partition cells. Furthermore, edges incident to such a group node are not considered during the layout.

Parameters:

fromRowIndex - the row index of the topmost row defining the cell

fromColIndex - the column index of the leftmost column defining the cell

toRowIndex - the row index of the bottommost row defining the cell

toColIndex - the column index of the rightmost column defining the cell

Returns:

a PartitionCellId instance

createCellSpanId

public PartitionCellId createCellSpanId(java.util.Collection rowList,
                                        java.util.Collection columnList)

Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.

The partition cell identifier represents all cells spanned by the columns of columnList and rows of rowList.

A group node mapped to such a partition cell identifier represents the multi-cell, i.e., its boundary corresponds to the smallest rectangle containing all partition cells specified by the partition cell identifier. The boundary does not depend on the partition cells associated with the group's descendants. Hence, each non-group descendant has to be manually assigned to one of the partition cells. Furthermore, edges incident to such a group node are not considered during the layout.

Parameters:

rowList - the rows defining the cell

columnList - the columns defining the cell

Returns:

a PartitionCellId instance

createCellSpanId

public PartitionCellId createCellSpanId(RowDescriptor fromRow,
                                        ColumnDescriptor fromCol,
                                        RowDescriptor toRow,
                                        ColumnDescriptor toCol)

Creates a partition cell identifier that represents a multi-cell spanning multiple columns and rows.

The partition cell identifier represents all cells defined by a row between fromRow and toRow (both including) and a column between fromRow and toCol (both including).

A group node mapped to such a partition cell identifier represents the multi-cell, i.e., its boundary corresponds to the smallest rectangle containing all partition cells specified by the partition cell identifier. The boundary does not depend on the partition cells associated with the group's descendants. Hence, each non-group descendant has to be manually assigned to one of the partition cells. Furthermore, edges incident to such a group node are not considered during the layout.

Parameters:

fromRow - the topmost row defining the cell

fromCol - the leftmost column defining the cell

toRow - the bottommost row defining the cell

toCol - the rightmost column defining the cell

Returns:

a PartitionCellId instance

createRowSpanId

public PartitionCellId createRowSpanId(int rowIndex)

Creates a partition cell identifier that represents a cell spanning a whole row.

A group node mapped to such a partition cell identifier represents the row, i.e., its enclosing boundary corresponds to that of the row. The boundary does not depend on the partition cells associated with the group's descendants. Hence, each non-group descendant has to be manually assigned to one of the partition cells. Furthermore, edges incident to such a group node are not considered during the layout.

Parameters:

rowIndex - the row index of the row defining the cell

Returns:

a PartitionCellId instance

getPartitionGrid

public static PartitionGrid getPartitionGrid(Graph graph)

Returns the PartitionGrid instance associated with the given graph.

Parameters:

graph - the given graph

Returns:

the PartitionGrid of the graph or null if the graph has no associated partition grid

addRow

public RowDescriptor addRow()

Adds a new row to the PartitionGrid instance. The index of the row (as returned by RowDescriptor.getIndex()) is equal to the size of the list returned by getRows().

Returns:

a new RowDescriptor instance

addColumn

public ColumnDescriptor addColumn()

Adds a new column to the PartitionGrid instance. The index of the column (as returned by ColumnDescriptor.getIndex()) is equal to the size of the list returned by getColumns().

Returns:

a new ColumnDescriptor instance

getRow

public RowDescriptor getRow(int index)

Returns the row with the given index.

Parameters:

index - the index of the row to be returned

Returns:

the row with the given index or null if no such row exists

getColumn

public ColumnDescriptor getColumn(int index)

Returns the column with the given index.

Parameters:

index - the index of the column to be returned

Returns:

the column with the given index or null if no such column exists

getRows

public YList getRows()

Returns the list of rows of the partition grid.

Returns:

the list of rows of this PartitionGrid

getColumns

public YList getColumns()

Returns the columns of the partition grid.

Returns:

the list of columns of this PartitionGrid

createCellId

public PartitionCellId createCellId(RowDescriptor rd,
                                    ColumnDescriptor cd)

Creates a partition cell identifier that represents the cell defined by the given column and row.

Parameters:

rd - the row defining the cell

cd - the column defining the cell

Returns:

a PartitionCellId instance

Throws:

java.lang.IllegalArgumentException - if the given column/row is null

createCellId

public PartitionCellId createCellId(int rowIndex,
                                    int columnIndex)

Creates a partition cell identifier that represents the cell defined by the given column and row index.

Parameters:

rowIndex - the row index of the row defining the cell

columnIndex - the column index of the column defining the cell

Returns:

a PartitionCellId instance

Throws:

java.lang.IllegalArgumentException - if the given column/row index is not valid

optimizeRowOrder

public void optimizeRowOrder(Graph g)

Optimizes the order of the rows of the PartitionGrid for the given graph.

This method is for internal use only! To use the column order optimization, set setRowOrderOptimizationEnabled(boolean) to true.

Parameters:

g - the given graph

optimizeColumnOrder

public void optimizeColumnOrder(Graph g)

Optimizes the order of the columns of the PartitionGrid for the given graph.

This method is for internal use only! To use the column order optimization, set setColumnOrderOptimizationEnabled(boolean) to true.

Parameters:

g - the given graph

finalizeOrientationChange

public void finalizeOrientationChange(OrientationLayouter orientationLayouter,
                                      OrientationLayouter.Transformer transformer)

Finalizes the orientation changes and is called at the end of the OrientationLayouter stage.

Points are transferred to their final positions through OrientationLayouter.Transformer.finalizeTransform(YPoint).

Parameters:

orientationLayouter - an OrientationLayouter instance

transformer - an OrientationLayouter.Transformer instance

See Also:

OrientationLayouter

prepareOrientationChange

public void prepareOrientationChange(OrientationLayouter orientationLayouter,
                                     OrientationLayouter.Transformer transformer)

Prepares for the orientation changes and is called at the beginning of the OrientationLayouter stage.

Original points are transferred to their temporary positions through OrientationLayouter.Transformer.initTransform(YPoint).

Parameters:

orientationLayouter - an OrientationLayouter instance

transformer - an OrientationLayouter.Transformer instance

See Also:

OrientationLayouter