C

TabularLayout

Show Usages
This layout algorithm places nodes in a tabular fashion.
ImplementsInheritance Hierarchy

Remarks

Layout Style

The nodes are placed based on an underlying LayoutGrid structure. Only nodes are arranged, edges are not routed, but their bend points are cleared. Therefore, this algorithm is suitable if nodes should be arranged in rows and columns in a regular fashion.

A tabular layout of 8 nodes organized in a 3x3 grid

A tabular layout of 8 nodes organized in a 2x6 grid with some gaps (empty cells)

Concept

The table consists of LayoutGridCellDescriptors which form rows and columns. Each cell contains a single node or might also be empty. Note that it is not required that the input graph already contains a LayoutGrid for this algorithm to properly work. It is, however, useful if the resulting row and column geometry should be retrieved (e.g. to visualize the table). It is mandatory to register a LayoutGrid when using layout policy FIXED_SIZE.

Rows/columns do not overlap and are not compacted: nodes that belong to different rows are strictly separated with respect to the covered y-coordinate range and nodes that belong to different columns are strictly separated with respect to the covered x-coordinate range.

Features

It is possible to define in which cell of the table a certain node should be placed when using policy FIXED_SIZE. See the policy documentation for more details.

The algorithm considers the following properties associated with LayoutGridRows and LayoutGridColumns of a LayoutGrid registered with the input graph:

Group nodes are supported but only top-level groups are handled like an actual node in the table. The content of top-level groups is kept fixed. That means that the content keeps the relative location with respect to the top-level group but it is not recursively arranged in a tabular fashion. To achieve recursive layouts where the content is a tabular layout too, use RecursiveGroupLayout with TabularLayout as core layout algorithm. Generally, it is recommended that group nodes already have proper bounds enclosing all content (and their labels). Otherwise, overlaps may occur, as group node sizes are not changed by this algorithm. RecursiveGroupLayout with FIX_CONTENT_LAYOUT as core algorithm can be used to recursively assign group node sizes.

Layout Stages

This class provides a configurable pipeline that contains various ILayoutStages. Each ILayoutStage can incorporate preprocessing or postprocessing steps into the layout calculation to streamline the input graph and enhance the resulting layout. Additionally, custom ILayoutStages can be added and executed either before or after the predefined ones.

The following default ILayoutStages are included:

With these layoutStages the layout algorithm is configured well, so they usually don't need to be changed.

Default Values of Properties

NameDefaultDescription
considerEdgesfalse
Edges are not considered.
defaultNodeDescriptorTabularLayoutNodeDescriptor
Descriptor instance with default settings.
edgeLabelPlacementTabularLayoutEdgeLabelPlacement.GENERIC
Edge labels are placed by an independent labeling algorithm.
layoutModeTabularLayoutMode.AUTO_SIZE
nodeLabelPlacementNodeLabelPlacement.CONSIDER
Node labels are considered.
stopDurationTimeSpan.MAX_VALUE
The layout algorithm runs unrestricted.

See Also

Developer's Guide

API

LayoutGrid

Members

Show:

Constructors

TabularLayout

()
Initializes a new instance of the TabularLayout class with default settings.

Parameters

Properties

considerEdges

: boolean
Gets or sets whether the algorithm should consider edges so that it tries to find a node arrangement with a low overall edge length.
Considering edges means that the algorithm applies a heuristic approach that prefers an arrangement of nodes that lead to a low overall edge length. It is still possible to define the exact table cell for a subset of the nodes, see policy FIXED_SIZE.
This option does not change the routing style of edges, i.e., all edges are still drawn as straight-lines. If desired, edges can be routed orthogonally by running, for example, the EdgeRouter after the TabularLayout.
Enabling this option increases the runtime especially for large graphs. Hence, limiting the stopDuration may be an option.
This option takes effect only if layoutMode is set to AUTO_SIZE or FIXED_SIZE, and if there is no custom node order specified.
final

Property Value

true if edges should be considered, false otherwise

Default Value

The default value is: false
Edges are not considered.

Sample Graphs

ShownSetting: true - edges are considered

See Also

Developer's Guide
API
layoutMode, freeNodeComparator

defaultNodeDescriptor

: TabularLayoutNodeDescriptor
Gets or sets the TabularLayoutNodeDescriptor instance that defines settings for those nodes that do not have an individual descriptor specified.
To define individual settings per item (node), use the layout data property nodeDescriptors.
final

Property Value

the default TabularLayoutNodeDescriptor instance

Throws

Exception ({ name: 'ArgumentError' })
if the specified descriptor is null

Default Value

The default value is: TabularLayoutNodeDescriptor
Descriptor instance with default settings.

See Also

Developer's Guide
API
nodeDescriptors

edgeLabelPlacement

: TabularLayoutEdgeLabelPlacement
Gets or sets how the layout handles the position of edge labels.
conversionfinal

Property Value

IGNORE if the edge labels are ignored by the layout algorithm, and GENERIC if the edge labels are placed by an independent labeling algorithm subsequently.

Default Value

Edge labels are placed by an independent labeling algorithm.

See Also

Developer's Guide

genericLabeling

: GenericLabeling
readonly
Gets the GenericLabeling helper class from the layoutStages of this instance.
If you need to replace the instance, modify the layoutStages stack using replace. If you want to remove a stage, consider disabling it instead.
readonlyfinal

Throws

Exception ({ name: 'InvalidOperationError' })
If there is no instance of the respective type in the layoutStages

layoutMode

: TabularLayoutMode
Gets or sets the policy defining the size of the resulting tabular layout and the mapping of the nodes to the table cells.
This policy is a crucial setting for the algorithm and should be chosen depending on the desired use case. Overview over the policies:
  • AUTO_SIZE: no LayoutGrid instance required. The size of the table is chosen automatically and nodes are sorted using a comparison function specified with property freeNodeComparator.
  • FIXED_SIZE: requires a registered LayoutGrid instance that defines the size of the tabular layout and, optionally, the mapping of nodes to specific cells.
  • FROM_SKETCH: no LayoutGrid instance required. The size of the table and the positioning of the nodes is solely derived from the coordinates of the input graph (sketch).
conversionfinal

Property Value

one of the predefined layout policies

Default Value

The default value is: TabularLayoutMode.AUTO_SIZE

See Also

Developer's Guide

nodeLabelPlacement

: NodeLabelPlacement
Gets or sets how the layout handles the position of node labels.
conversionfinal

Property Value

CONSIDER if the layout algorithm takes the position and sizes of the node labels into account, IGNORE if the node labels are ignored by the layout algorithm, and GENERIC if the node labels are placed by an independent labeling algorithm subsequently.

Default Value

The default value is: NodeLabelPlacement.CONSIDER
Node labels are considered.

Sample Graphs

ShownSetting: IGNORE

See Also

Developer's Guide

stopDuration

: TimeSpan
Gets or sets the time limit set for the layout algorithm.
Values have to be greater or equal to ZERO.
Restricting the stop duration may result in a lower layout quality. Furthermore, the real runtime may exceed the stop duration since the layout algorithm still has to find a valid solution.
Currently, this property only has an effect if considerEdges is enabled. Otherwise, the algorithm is already very fast.
conversionfinal

Property Value

a non-negative value that specifies the time limit

Throws

Exception ({ name: 'ArgumentError' })
if the stop duration is negative

Default Value

The default value is: TimeSpan.MAX_VALUE
The layout algorithm runs unrestricted.

Methods

applyLayout

(graph: LayoutGraph)
Calculates a tabular layout of the graph.
In contrast to applyLayoutCore, graph and layouter are prepared for an independent layout run.
The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.

Parameters

graph: LayoutGraph
the input graph

applyLayoutCore

(graph: LayoutGraph)
protected
Arranges the input graph in a tabular fashion.
protectedfinal

Parameters

graph: LayoutGraph
the input graph

createLayoutData

(graph: LayoutGraph): TabularLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the TabularLayout.
The generic type arguments of the created layout data are compatible with instances of LayoutGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.

Parameters

graph: LayoutGraph
the graph that determines the generic type arguments of the created layout data

Return Value

TabularLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
an instance of layout data that can be used to perform item-specific configurations for the given TabularLayout.

createLayoutData

(graph?: IGraph): TabularLayoutData<INode, IEdge, ILabel, ILabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the TabularLayout.
The generic type arguments of the created layout data are compatible with instances of IGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.
This method is not available unless the module view-layout-bridge is loaded. Either load the module 'view-layout-bridge' explicitly or ensure that the LayoutExecutor type is available at runtime.

Parameters

graph?: IGraph
the graph that determines the generic type arguments of the created layout data

Return Value

TabularLayoutData<INode, IEdge, ILabel, ILabel>
an instance of layout data that can be used to perform item-specific configurations for the given TabularLayout.

See Also

Developer's Guide

Constants

All constants are filtered. Go to Filters.