C

LayoutGraph

Show Usages
Represents a directed graph structure that contains layout information for its elements and to which layout algorithms (ILayoutAlgorithm) can be applied.
Inheritance Hierarchy

Remarks

A directed graph consists of a collection of "nodes" (represented by instances of LayoutNode) and "edges" (represented by instances of LayoutEdge) that connect pairs of nodes.

By default, the LayoutGraph contains layout information, such as the position and size of nodes (layout), and edge paths (pathPoints). Therefore, a LayoutGraph instance typically represents a visual drawing of a graph. If layout information is unnecessary, a more lightweight graph instance can be created using createStructureGraph, which only maintains the graph's structure without layout or labels. This is useful for performance-critical scenarios where only structural algorithms like shortestPath or pageRank are applied.

The class supports operations such as node and edge creation, deletion, access, and iteration through properties like nodes and edges. Additionally, nodes and edges can have associated labels, accessible via nodeLabels and edgeLabels.

Structural changes to the graph (such as adding or removing nodes/edges) must be made through the LayoutGraph instance, ensuring consistent graph manipulation.

In addition to basic node and edge management, the LayoutGraph supports the hierarchical grouping of nodes. Nodes can be designated as group nodes, which can contain other nodes, including other group nodes, forming a hierarchical structure. Methods such as createGroupNode, setParent, and setIsGroupNode allow the creation and manipulation of such groups.

Group nodes are useful for organizing complex graph structures, where nodes can be logically grouped together. The grouping hierarchy can be queried using methods like getChildren and getParent, enabling navigation and management of the nested structure. This functionality is particularly helpful in scenarios where visual grouping or compartmentalization of nodes is required.

Data access and manipulation are also supported via IMapper<K, V>, allowing custom data to be associated with nodes and edges.

See Also

Developer's Guide

Members

Show:

Constructors

LayoutGraph

()
Instantiates an empty LayoutGraph object.

Properties

bends

: IEnumerable<LayoutBend>
readonly
Provides an IEnumerable<T> of LayoutBends, allowing iteration over all bends of the edges of the graph.
This is a view of the currently contained bends - a new enumerable instance is provided on each invocation. Changes to the graph structure during traversal should be avoided.
readonlyfinal

context

: LayoutGraphContext
readonly
Gets the context associated with this graph.
The LayoutGraphContext provides additional data for the graph and its elements that can be utilized by layout algorithms.
readonlyfinal

See Also

API
LayoutGraphContext

edgeLabels

: IEnumerable<LayoutEdgeLabel>
readonly
Gets a live view of all LayoutEdgeLabel instances contained in this graph.
Changes to the graph's structure or labels will be reflected in this view.
readonlyfinal

Property Value

A dynamic view of all edge labels in the graph.

edges

: ILinkedItemEnumerable<LayoutEdge>
readonly
Provides a dynamic IEnumerable<T> for LayoutEdges, allowing iteration over the edges contained in this instance.
This is a live enumerable that reflects the current state of the graph. Note that changes to the graph structure during traversal should be performed with caution.
readonlyfinal

See Also

Developer's Guide

isEmpty

: boolean
readonly
Gets a value indicating whether this graph is empty, that is, contains no nodes.
readonlyfinal

Property Value

true if this graph contains no nodes; otherwise, false.

nodeLabels

: IEnumerable<LayoutNodeLabel>
readonly
Gets a live view of all LayoutNodeLabel instances contained in this graph.
readonlyfinal

Property Value

A dynamic view of all node labels in the graph. Any changes to the graph's structure or labels will be reflected in this view.

nodes

: ILinkedItemEnumerable<LayoutNode>
readonly
Provides a dynamic IEnumerable<T> for LayoutNodes, allowing iteration over the nodes contained in this instance.
This is a live enumerable that reflects the current state of the graph. Note that changes to the graph structure during traversal should be performed with caution.
readonlyfinal

See Also

Developer's Guide

Methods

addBend

(
edge: LayoutEdge
x: number
y: number
reference?: LayoutBend
insertion?: RelativePosition
): LayoutBend
Creates a new bend point for the given edge with the specified coordinates.
If the edge already contains bend points and no reference is specified, the new bend will be appended closest to the edge's target node, after all existing bends. If a reference is provided, the new bend will be inserted relative to that reference bend, based on the insertion.
final

Parameters

edge: LayoutEdge
The edge to which the bend will be added.
x: number
The x-coordinate of the new bend.
y: number
The y-coordinate of the new bend.
reference?: LayoutBend
An optional existing bend adjacent to which the new bend will be created. If omitted, the bend is appended near the edge's target port.
insertion?: RelativePosition
Specifies whether the new bend should be inserted before or after the reference. If reference is null, this parameter is ignored. Use BEFORE to insert the bend in the direction of the source node, or AFTER to insert it toward the target node.

Return Value

LayoutBend
The newly created LayoutBend instance.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if edge does not belong to this graph, or if x or y contain a Number.NaN value.

addLabel

(node: LayoutNode, layout: IOrientedRectangle): LayoutNodeLabel
Creates a new label for the specified node with the given layout.
final

Parameters

node: LayoutNode
The node to which the label will be added.
layout: IOrientedRectangle
An IOrientedRectangle that defines the label's boundary and orientation.

Return Value

LayoutNodeLabel
The newly created LayoutNodeLabel instance.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node does not belong to this graph, or if the layout contains a Number.NaN value.

See Also

Developer's Guide

addLabel

(edge: LayoutEdge, layout: IOrientedRectangle): LayoutEdgeLabel
Creates a new label for the specified edge with the given layout.
final

Parameters

edge: LayoutEdge
The edge to which the label will be added.
layout: IOrientedRectangle
An IOrientedRectangle that defines the label's boundary and orientation.

Return Value

LayoutEdgeLabel
The newly created LayoutEdgeLabel instance.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if edge does not belong to this graph, or if the layout contains a Number.NaN value.

See Also

Developer's Guide

addLabel

(
node: LayoutNode
width: number
height: number
): LayoutNodeLabel
Creates a new label for the specified node with the given dimensions.
final

Parameters

node: LayoutNode
The node to which the label will be added.
width: number
The width of the label's boundary.
height: number
The height of the label's boundary.

Return Value

LayoutNodeLabel
The newly created LayoutNodeLabel instance.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node does not belong to this graph, or if width or height contain a Number.NaN value.

addLabel

(
edge: LayoutEdge
width: number
height: number
): LayoutEdgeLabel
Creates a new label for the specified edge with the given dimensions.
final

Parameters

edge: LayoutEdge
The edge to which the label will be added.
width: number
The width of the label's boundary.
height: number
The height of the label's boundary.

Return Value

LayoutEdgeLabel
The newly created LayoutEdgeLabel instance.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if edge does not belong to this graph, or if width or height contain a Number.NaN value.

applyLayout

(layout: ILayoutAlgorithm, layoutData?: LayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>)
Runs an ILayoutAlgorithm synchronously on the given LayoutGraph, applying the given layoutData.

Parameters

layout: ILayoutAlgorithm
The layout.
layoutData?: LayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
The layout data.

See Also

Developer's Guide

changeEdge

(
edge: LayoutEdge
newSource: LayoutNode
newTarget: LayoutNode
sourceReference?: LayoutEdge
sourceInsertion?: RelativePosition
targetReference?: LayoutEdge
targetInsertion?: RelativePosition
)
Redefines the endpoints of the specified edge, changing its source and target nodes.

You can specify the order in which the edge should be inserted into the incoming/outgoing edges of the source/target nodes using the reference edge parameters.

The actual new source/target node will be determined based on the reference edges provided. If the reference edges are omitted, the edge will be appended to the lists of incoming and outgoing edges at the new source and target nodes, respectively.

For example, providing AFTER as sourceInsertion will insert the edge after the sourceReference edge when iterating through the outgoing edges at the source node.

final

Parameters

edge: LayoutEdge
The edge to be modified.
newSource: LayoutNode
The new source node for the specified edge.
newTarget: LayoutNode
The new target node for the specified edge.
sourceReference?: LayoutEdge
Optional. A reference edge for insertion at the new source node. If provided, its target must be the given node newSource.
sourceInsertion?: RelativePosition
Optional. Specifies whether to insert the edge immediately BEFORE or AFTER the sourceReference edge. This parameter is ignored if the source reference is null.
targetReference?: LayoutEdge
Optional. A reference edge for insertion at the new target node. If provided, its target must be the given node newTarget.
targetInsertion?: RelativePosition
Optional. Specifies whether to insert the edge immediately BEFORE or AFTER the targetReference edge. This parameter is ignored if the target reference is null.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if the new source or target node is null.
Exception ({ name: 'ArgumentError' })
If the new source is not the source of the given sourceReference edge or the target node is not the target of the given targetReference edge.

See Also

Developer's Guide

clear

()
Removes all nodes and edges from this graph.
final

See Also

Developer's Guide

contains

(node: LayoutNode): boolean
Determines whether this graph contains the specified node.
final

Parameters

node: LayoutNode
The node to check for existence in the graph.

Return Value

boolean
true if this graph contains the specified node; otherwise, false.

contains

(edge: LayoutEdge): boolean
Determines whether this graph contains the specified edge.
final

Parameters

edge: LayoutEdge
The edge to check for existence in the graph.

Return Value

boolean
true if this graph contains the specified edge; otherwise, false.

contains

(label: LayoutNodeLabel): boolean
Determines whether this graph contains the specified node label.
final

Parameters

label: LayoutNodeLabel
The node label to check for existence in the graph.

Return Value

boolean
true if this graph contains the specified node label; otherwise, false.

contains

(label: LayoutEdgeLabel): boolean
Determines whether this graph contains the specified edge label.
final

Parameters

label: LayoutEdgeLabel
The edge label to check for existence in the graph.

Return Value

boolean
true if this graph contains the specified edge label; otherwise, false.

contains

(bend: LayoutBend): boolean
Determines whether this graph contains the specified bend.
final

Parameters

bend: LayoutBend
The bend to check for existence in the graph.

Return Value

boolean
true if this graph contains the specified bend; otherwise, false.
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

items: LayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
the layout data instances that should be combined into the created CompositeLayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel>

Return Value

CompositeLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>

createEdge

(
source: LayoutNode
target: LayoutNode
sourceReference?: LayoutEdge
sourceInsertion?: RelativePosition
targetReference?: LayoutEdge
targetInsertion?: RelativePosition
): LayoutEdge
Creates a new edge between the specified source and target nodes.
The edge can be inserted in a specific position relative to existing edges of the source and target nodes using the sourceReference and targetReference parameters. If no reference edges are provided, the edge is added at the end of the lists of incoming/outgoing edges.
final

Parameters

source: LayoutNode
The source node of the edge.
target: LayoutNode
The target node of the edge.
sourceReference?: LayoutEdge
The reference edge for positioning at the source node.
sourceInsertion?: RelativePosition
Defines whether the edge is inserted before or after sourceReference.
targetReference?: LayoutEdge
The reference edge for positioning at the target node.
targetInsertion?: RelativePosition
Defines whether the edge is inserted before or after targetReference.

Return Value

LayoutEdge
The newly created edge.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if source, target, the source of sourceReference or the target of targetReference are not part of this graph.

createGenericLayoutData

(): GenericLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to easily associate custom item-specific data with a LayoutGraph.
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.

Return Value

GenericLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
an instance of GenericLayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to easily associate custom item-specific data with a graph.

createGroupNode

(parent?: LayoutNode, layout?: Rect): LayoutNode
Creates a new group node as a direct descendant of parent using the optional specified layout.
final

Parameters

parent?: LayoutNode
The parent node in the grouping hierarchy. If null, the new group node becomes a top-level group node. Use setParent to change the parent after creation.
layout?: Rect
The initial layout for the group node. If not specified, the node is positioned at (0, 0) with a size of 30x30.

Return Value

LayoutNode
The newly created group node.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if parent is not contained in this graph.

See Also

Developer's Guide
API
setParent, getParent, layout

createNode

(layout: Rect): LayoutNode
Creates a new node using the specified layout.
final

Parameters

layout: Rect
The layout to use for the node's initial position and size.

Return Value

LayoutNode
The newly created node.

See Also

API
layout

createNode

(parent?: LayoutNode, layout?: Rect): LayoutNode
Creates a new node as a direct descendant of parent using the optional specified layout.
final

Parameters

parent?: LayoutNode
The parent node in the grouping hierarchy. If null, the new node becomes a top-level node. To change the parent after creation, use setParent.
layout?: Rect
The initial layout for the node, including position and size. The layout is copied to the node's layout property. If not specified, the node's position is set to (0, 0), and its size is set to 30x30.

Return Value

LayoutNode
The newly created node.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if parent is not a valid node in this graph or if layout contains invalid values (e.g., Number.NaN).

See Also

API
setParent, getParent, layout, createNode

getBounds

(
nodes?: IEnumerable<LayoutNode>
edges?: IEnumerable<LayoutEdge>
includeNodeLabels?: boolean
includeEdgeLabels?: boolean
includeMargins?: boolean
): Rect
Returns the bounds of the graph, optionally considering the specified nodes and edges, including node labels, edge labels, or node margins.
final

Parameters

nodes?: IEnumerable<LayoutNode>
The nodes whose geometry contributes to the bounds. If null or omitted, all nodes of the graph will be considered.
edges?: IEnumerable<LayoutEdge>
The edges whose geometry contributes to the bounds. If null or omitted, all edges of the graph will be considered.
includeNodeLabels?: boolean
A flag indicating whether to include node labels in the bounds calculation.
includeEdgeLabels?: boolean
A flag indicating whether to include edge labels in the bounds calculation.
includeMargins?: boolean
A flag indicating whether to include node margins in the bounds calculation.

Return Value

Rect
The calculated bounds of the specified nodes and edges.

getChildren

(node: LayoutNode): ILinkedItemEnumerable<LayoutNode>
Returns the children of the specified group node.

This method returns only the direct children, meaning all nodes that have node as their parent, as determined by the getParent method.

To obtain all descendants of the node, consider using the getDescendants method.

To make a node a child of node, utilize the setParent method.

final

Parameters

node: LayoutNode
The group node for which to return the children, or null if top-level nodes should be returned.

Return Value

ILinkedItemEnumerable<LayoutNode>
An enumerable collection of nodes that have node as their parent.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is not part of this graph.

See Also

Developer's Guide
API
getDescendants, setParent, getParent

getEdgesBetween

(
source: LayoutNode
target: LayoutNode
directed?: boolean
): IEnumerable<LayoutEdge>
Returns the edges between the specified source and target nodes.
By default, only directed edges are returned. To retrieve all edges (both incoming and outgoing), set directed to false.
final

Parameters

source: LayoutNode
The node from which the edges start.
target: LayoutNode
The node at which the edges end.
directed?: boolean
Specifies whether to return only directed edges (default) or all edges regardless of direction.

Return Value

IEnumerable<LayoutEdge>
An enumerable collection of edges connecting the source to the target.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if either source or target is not contained in this graph.

getParent

(node: LayoutNode): LayoutNode
Returns the parent node of a specified node, or null if the node is a top-level node.
final

Parameters

node: LayoutNode
The node for which to obtain the parent node.

Return Value

LayoutNode
The parent node in this hierarchy, or null if node is a top-level node.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is not part of this graph.

See Also

Developer's Guide
API
setParent, getChildren

isGroupNode

(node: LayoutNode): boolean
Determines whether the specified node is a group node.

Group nodes are nodes that can have children, as identified by the getChildren method. While they may have children, this is not a requirement.

The virtual root of the grouping hierarchy is represented by null, and top-level nodes are considered its 'children', thus making null also a group node in this context.

final

Parameters

node: LayoutNode
The node to check for group status.

Return Value

boolean
true if the node is considered a group node; otherwise, false.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is not part of this graph.

See Also

Developer's Guide
API
getChildren, setIsGroupNode, createGroupNode

reinsert

(node: LayoutNode)
Reinserts a previously removed node back into this graph.
The reinserted node is appended to the sequence of nodes in this graph. Its new position will likely differ from its position prior to removal.
final

Parameters

node: LayoutNode
The node to be reinserted.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is already present in the graph.

See Also

API
remove

reinsert

(edge: LayoutEdge)
Reinserts a previously removed edge back into this graph.

The reinserted edge is appended to the sequence of edges in this graph. Its new position will likely differ from its position prior to removal, including the edge's positions in the incoming and outgoing edges of its source and target nodes.

Attempting to reinsert an edge whose source or target node is not present in the graph will result in an exception. Therefore, the corresponding endpoints must be reinserted first.

final

Parameters

edge: LayoutEdge
The edge to be reinserted.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if edge is already present in a graph, or if either the source or target of edge is not present in this graph.

See Also

API
remove

remove

(edge: LayoutEdge)
Removes the specified edge from this graph.
If the edge is intended to be temporarily hidden, it can be reinserted using the reinsert method.
final

Parameters

edge: LayoutEdge
The edge to be removed.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if edge is not present in this graph.

remove

(node: LayoutNode)
Removes the specified node from this graph.

All edges connecting to the specified node will also be removed prior to the actual node removal.

If the node is intended to be temporarily hidden, it can be reinserted using the reinsert method.

final

Parameters

node: LayoutNode
The node to be removed.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is not present in this graph.

See Also

Developer's Guide

remove

(bend: LayoutBend)
Removes the given bend from the edge it belongs to and thus from this graph.
final

Parameters

bend: LayoutBend
The bend to remove.

Throws

Exception ({ name: 'ArgumentError' })
bend is not in this graph.

remove

(label: LayoutNodeLabel)
Removes the given label from its node.
final

Parameters

label: LayoutNodeLabel
The label to remove.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if label is not present in this graph.

See Also

Developer's Guide

remove

(label: LayoutEdgeLabel)
Removes the given label from its edge.
final

Parameters

label: LayoutEdgeLabel
The label to remove.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if label is not present in this graph.

See Also

Developer's Guide

reverseEdge

(edge: LayoutEdge)
Reverses the specified edge.
This method reverses the entire path of the edge, including bends, source and target port offsets, as well as the source and target nodes.
final

Parameters

edge: LayoutEdge
The edge to be reversed.

See Also

Developer's Guide

setIsGroupNode

(node: LayoutNode, isGroup: boolean)
Updates the group node status of a specified node.

This method allows the modification of a node's status to indicate whether it is a group node, which can have children as indicated by getChildren.

When this method is used to turn a group node into a normal node, it must first be assured that the node does not have any child nodes.

final

Parameters

node: LayoutNode
The node for which to set the group node status.
isGroup: boolean
A boolean indicating whether to make the node a group node (true) or not (false).

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is not part of this graph or if node still has child nodes

See Also

Developer's Guide
API
getChildren, isGroupNode

setParent

(node: LayoutNode, parent: LayoutNode)
Sets the parent node for a specified node.

Use null as parent to designate node as a top-level node in the graph.

If parent is not already a group node prior to this call, it will be automatically converted into a group node.

To retrieve the parent of a node, utilize the getParent method.

final

Parameters

node: LayoutNode
The node to which a new parent will be assigned.
parent: LayoutNode
The parent group node to be assigned to node, or null to make node a top-level node.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node or parent are not part of this graph.
Exception ({ name: 'InvalidOperationError' })
Thrown if the parent is a descendant of node or the node itself.

See Also

Developer's Guide
API
getParent

sortEdges

(comparator: function(LayoutEdge, LayoutEdge): number)
Sorts the list of LayoutEdge objects in this graph.
final

Parameters

comparator: function(LayoutEdge, LayoutEdge): number
A comparison delegate that defines the criteria for sorting the edges.

sortEdges

(inEdgeComparator: function(LayoutEdge, LayoutEdge): number, outEdgeComparator: function(LayoutEdge, LayoutEdge): number)
Sorts incoming and outgoing edges at each node of the graph.
If a given comparison function is null, then the corresponding edges (i.e., incoming/outgoing) will not be sorted. This method sorts the order of edges as returned by inEdges and outEdges respectively.
final

Parameters

inEdgeComparator: function(LayoutEdge, LayoutEdge): number
The comparison function used for sorting the incoming edges at each node. Set to null to skip sorting incoming edges.
outEdgeComparator: function(LayoutEdge, LayoutEdge): number
The comparison function used for sorting the outgoing edges at each node. Set to null to skip sorting outgoing edges.

sortNodes

(comparator: function(LayoutNode, LayoutNode): number)
Sorts the list of LayoutNode objects in this graph.
final

Parameters

comparator: function(LayoutNode, LayoutNode): number
A comparison delegate that defines the criteria for sorting the nodes.

toString

(): string
Returns a string representation of this graph.
The result contains the string representations of all nodes followed by the string representations of all edges in the graph.
final

Return Value

string
A string representation of this graph.

Static Methods

createStructureGraph

(): LayoutGraph
static
Creates a graph that represents a plain graph structure without layout information for its nodes and edges.

Creating an optimized graph is recommended for performance-critical applications where only the graph structure is relevant, and no ILayoutAlgorithm will be applied.

A graph created using this method cannot be processed by ILayoutAlgorithms. To create a LayoutGraph with layout capabilities, use the standard constructor.

Layout properties of LayoutNodes and LayoutEdges can be written and accessed without exceptions, but they have no meaningful effect on a graph created with this method. The same applies when trying to add bends or add labels. Therefore, it must be avoided to read and write layout-related information on a graph created with this method!
static

Return Value

LayoutGraph
A new LayoutGraph instance representing a plain graph structure without layout information.