Tabular Layout
Class TabularLayout is a layout algorithm that places nodes in a tabular fashion.
TabularLayout can be considered an algorithm for producing simple tabular/grid-like layouts of nodes:
- Each table cell contains at most one node.
- The connectivity of nodes is ignored.
- The edges are not routed.
Sample layout by class TabularLayout: a simple table with 3 rows and 3 columns shows a sample result. The depicted layout contains 8 nodes which are organized in a 3x3 table. Sample layout by class TabularLayout: a table with 2 rows and 6 columns shows a layout with 7 nodes that are organized in a 2x6 table. Here, some cells are not occupied, i.e., there are gaps in the table. The second example also visualizes the actual table cells.
For other algorithms that support more complex tabular layouts featuring edge routing, please see Layout of Tables and Swimlanes.
Relation to Partition Grid
Class PartitionGrid represents a general API for table layouts in yFiles, see also Layout of Tables and Swimlanes. Algorithm TabularLayout described here uses that API, but does not necessarily rely on it. Depending on the scenario, there is no need to define a PartitionGrid instance on the input graph.
The two layout policies Auto-Size and From-Sketch do not require an existing PartitionGrid. So, if only a node arrangement in a tabular fashion is desired, no grid instance is necessary. See, for example, Sample layout by class TabularLayout: a simple table with 3 rows and 3 columns where the table itself is not visualized.
Independent of the layout policy, a PartitionGrid is required if:
- The table itself should be visualized (as nodes or also by other means), because the coordinates of the rows and columns and their sizes can be retrieved from it, as shown in Sample layout by class TabularLayout: a table with 2 rows and 6 columns.
- Specific settings like minimum height/width for a specific row/column should be obeyed, as these settings are bound to RowDescriptor or ColumnDescriptor objects defined on the PartitionGrid instance.
When using class TableLayoutConfigurator to create the PartitionGrid from a Table, it is required that layout policy Fixed Size is specified.
Layout Policies
The property layoutPolicy represents a crucial setting that should be chosen depending on the use-case.
The policy affects the size of the table, that is, the number of rows and columns. Also, depending on the policy, the configuration of a PartitionGrid instance registered with the input graph is either consider or not.
In the following, the available policies are described.
Auto-Size
Policy AUTO_SIZE automatically derives the table size from the number of nodes in the input graph. The size will be chosen such that both row count and column count are similar, leading to a maximally square table (note that the actual node sizes are not considered).
Example: given a graph with 16 nodes, the resulting table will have four rows and four columns.
If a PartitionGrid is registered with the input graph, only the settings of the first row/column are used as template settings (i.e., settings like insets and minimum width/height are transferred to the resulting rows/columns).
Fixed Size
Policy FIXED_SIZE obeys the row and column count exactly as given by the PartitionGrid instance defined on the input graph.
In consequence, this policy requires that a valid grid is registered and that the grid contains enough rows and columns to fit all the nodes. Otherwise, an exception will be thrown.
This policy also allows to map a node to a specific cell, e.g., to state that a node should be in the row and column with a specific index. To do so, use PartitionGridData.cellIds. See Supplemental layout data for more information on how to define this supplemental data.
Multi-cells, that is, PartitionCellIds that span multiple cells are not allowed.
In the following, a code example using the fixed size policy is shown. It configures the algorithm to generate a single-column layout.
const graph = getMyGraph()
const tabularLayout = new TabularLayout()
// Set the policy to fixed size, as we want to define the dimension of the table/grid ourselves
tabularLayout.layoutPolicy = TabularLayoutPolicy.FIXED_SIZE
// Define a n x 1 partition grid (n rows, 1 column) on the partition grid data of the tabular layout data,
// where n is the number of nodes in the graph. This grid defines the dimension of the tabular layout
const data = new TabularLayoutData({
partitionGridData: new PartitionGridData({
grid: new PartitionGrid(graph.nodes.size, 1)
})
})
// Apply the tabular layout algorithm
graph.applyLayout(tabularLayout, data)
const graph: IGraph = getMyGraph()
const tabularLayout = new TabularLayout()
// Set the policy to fixed size, as we want to define the dimension of the table/grid ourselves
tabularLayout.layoutPolicy = TabularLayoutPolicy.FIXED_SIZE
// Define a n x 1 partition grid (n rows, 1 column) on the partition grid data of the tabular layout data,
// where n is the number of nodes in the graph. This grid defines the dimension of the tabular layout
const data = new TabularLayoutData({
partitionGridData: new PartitionGridData({
grid: new PartitionGrid(graph.nodes.size, 1)
})
})
// Apply the tabular layout algorithm
graph.applyLayout(tabularLayout, data)
From-Sketch
Policy FROM_SKETCH takes the coordinates of the nodes in the input graph into account to derive a tabular layout. Nodes are assigned to the same row if there exists a horizontal line that crosses through both of them. Similarly, nodes are assigned to the same column if there exists a vertical line that crosses through both of them. This strategy only works smoothly if the given input already resembles a rough table arrangement. It is not recommended that the input graph contains node overlaps, as the mapping to rows/columns becomes ambiguous.
If a PartitionGrid is registered with the input graph, only the settings of the first row/column are used as template settings (i.e., settings like insets and minimum width/height are transferred to the resulting rows/columns).
Basic Options
Despite the layout policy described in the last section, there are more basic settings that allow to customize the tabular layout produced by TabularLayout.
Node Layout Descriptor
Node-related options can be specified by means of class TabularNodeLayoutDescriptor. It is, for example, possible to define the desired horizontal or vertical alignment of nodes within their respective columns and rows. TabularLayout holds a descriptor instance that provides the default settings:
- defaultNodeLayoutDescriptor
- The default node-related layout options
In addition to the default descriptor, layout descriptors can also be associated with single nodes in order to specify individual settings for them. Setting individual descriptors for nodes can conveniently be done by using layout data instances for the layout algorithm. See also Layout Data.
More General Settings
There are several additional settings which are not discussed explicitly here. See the following list for an overview and consult the respective API documentation for details.
- nodeComparer
- Used to sort the nodes in mode Auto-Size and the free nodes in mode Fixed Size.
- considerEdges
- Whether or not edges are considered. Considering edges means that the algorithm applies a heuristic approach that prefers an arrangement of the free nodes that lead to a low overall edge length.
- considerNodeLabels
- Whether or not node labels are considered.
Layout Data
When using class TabularLayout, supplemental layout data for a graph’s elements can be specified either by using class TabularLayoutData or by registering data providers with the graph using given look-up keys.
Supplemental layout data lists all properties of TabularLayoutData and the corresponding look-up keys that TabularLayout tests during the layout process in order to query supplemental data.
Providing supplemental layout data is described in detail in Layout Data.
Supplemental layout data
nodeLayoutDescriptors - For each node a TabularNodeLayoutDescriptor object that configures node-related settings like the alignment.Data Provider Key: NODE_LAYOUT_DESCRIPTOR_DP_KEYMaps from node to NodeLayoutDescriptor
nodeHalos - A NodeHalo object that specifies the halo sizes at each side of a node.Data Provider Key: NODE_HALO_DP_KEYMaps from node to NodeHalo
partitionGridData - Specifies a PartitionGrid for the tabular layout.
- PartitionGridData.grid
- Specifies the partition grid structure for the graph. Can also be defined using the rowIndices and columnIndices properties.Data Provider Key: PARTITION_GRID_DP_KEYMaps from graph to PartitionGrid
- PartitionGridData.cellIds
- Specifies the cell id for a node. Alternatively, cell indices for a node can be specified using the rowIndices and columnIndices properties.Data Provider Key: PARTITION_CELL_ID_DP_KEYMaps from node to PartitionCellId