com.yworks.yfiles.layout

Class PartitionGrid

java.lang.Object

com.yworks.yfiles.layout.PartitionGrid

public class PartitionGrid
extends 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 IDataProvider 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 IDataProvider key PARTITION_CELL_ID_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

A group node mapped to a multi-cell identifier represents the corresponding multi-cell, i.e., its boundary corresponds to the smallest rectangle containing all partition cells (rows and columns) specified by the multi-cell. 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. Mapping a group node to a simple partition cell identifier has no effect.

If at least one node is mapped to a multi-cell, enabling option ColumnOrderOptimizationEnabled or RowOrderOptimizationEnabled has no effect.

Field Summary

Fields

Modifier and Type	Field and Description
static NodeDpKey<PartitionCellId>	PARTITION_CELL_ID_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 GraphDpKey<PartitionGrid>	PARTITION_GRID_DPKEY A DataProvider key for storing the partition grid structure If the IDataProvider contains a partition grid structure, this structure will be considered during layout (provided that the layout algorithm supports such constraints).

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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(Collection<Object> rowList, Collection<Object> 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(OrientationLayout orientationLayouter) Finalizes the orientation changes and is called at the end of the OrientationLayout stage.
ColumnDescriptor	getColumn(int index) Returns the column with the given index.
YList	getColumns() Gets 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() Gets the list of rows of the partition grid.
static boolean	hasAtLeastTwoNonEmptyRows(Graph graph) Checks whether or not the nodes of the graph are assigned to at least two different partition rows.
boolean	isColumnOrderOptimizationEnabled() Gets whether or not the order of the columns should be chosen automatically to minimize edge lengths.
boolean	isRowOrderOptimizationEnabled() Gets whether or not the order of the rows should be chosen automatically to minimize edge lengths.
void	prepareOrientationChange(OrientationLayout orientationLayouter) Prepares for the orientation changes and is called at the beginning of the OrientationLayout stage.
void	setColumnOrderOptimizationEnabled(boolean value) Sets whether or not the order of the columns should be chosen automatically to minimize edge lengths.
void	setRowOrderOptimizationEnabled(boolean value) Sets 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_CELL_ID_DPKEY

public static final NodeDpKey<PartitionCellId> PARTITION_CELL_ID_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

PARTITION_GRID_DPKEY

public static final GraphDpKey<PartitionGrid> PARTITION_GRID_DPKEY

A DataProvider key for storing the partition grid structure

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

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

addColumn

public ColumnDescriptor addColumn()

Adds a new column to the PartitionGrid instance.

The index of the column (as returned by Index) is equal to the size of the list returned by Columns.

Returns:

a new ColumnDescriptor instance

addRow

public RowDescriptor addRow()

Adds a new row to the PartitionGrid instance.

The index of the row (as returned by Index) is equal to the size of the list returned by Rows.

Returns:

a new RowDescriptor instance

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.

Throws:

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

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

createCellId

public PartitionCellId createCellId(RowDescriptor rd,
                                    ColumnDescriptor cd)

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

Throws:

IllegalArgumentException - if the given column/row is null

Parameters:

rd - the row defining the cell

cd - the column defining the cell

Returns:

a PartitionCellId instance

createCellSpanId

public PartitionCellId createCellSpanId(Collection<Object> rowList,
                                        Collection<Object> 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(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(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

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

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

finalizeOrientationChange

public void finalizeOrientationChange(OrientationLayout orientationLayouter)

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

Points are transferred to their final positions through OrientationLayout.completeTransform(YPoint).

Parameters:

orientationLayouter - an OrientationLayout instance

See Also:

OrientationLayout

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

getColumns

public YList getColumns()

Gets the columns of the partition grid.

Returns:

the list of columns of this PartitionGrid

getPartitionGrid

public static final 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

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

getRows

public YList getRows()

Gets the list of rows of the partition grid.

Returns:

the list of rows of this PartitionGrid

hasAtLeastTwoNonEmptyRows

public static final boolean hasAtLeastTwoNonEmptyRows(Graph graph)

Checks whether or not the nodes of the graph are assigned to at least two different partition rows.

Parameters:

graph - the input graph

Returns:

true if the nodes of the graph are assigned to at least two different partition rows, false otherwise

isColumnOrderOptimizationEnabled

public boolean isColumnOrderOptimizationEnabled()

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

For all columns where IndexFixed 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.

Returns:

true if the order is chosen automatically, false otherwise

See Also:

setColumnOrderOptimizationEnabled(boolean)

isRowOrderOptimizationEnabled

public boolean isRowOrderOptimizationEnabled()

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

For all rows where IndexFixed 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.

Returns:

true if the order is chosen automatically, false otherwise

See Also:

setRowOrderOptimizationEnabled(boolean)

prepareOrientationChange

public void prepareOrientationChange(OrientationLayout orientationLayouter)

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

Original points are transferred to their temporary positions through OrientationLayout.prepareTransform(YPoint).

Parameters:

orientationLayouter - an OrientationLayout instance

See Also:

OrientationLayout

setColumnOrderOptimizationEnabled

public void setColumnOrderOptimizationEnabled(boolean value)

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

For all columns where IndexFixed 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:

value - true if the order is chosen automatically, false otherwise

See Also:

isColumnOrderOptimizationEnabled()

setRowOrderOptimizationEnabled

public void setRowOrderOptimizationEnabled(boolean value)

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

For all rows where IndexFixed 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:

value - true if the order is chosen automatically, false otherwise

See Also:

isRowOrderOptimizationEnabled()