C

LayoutGraphGrouping

Show Usages
Provides access to the hierarchical structure of a LayoutGraph in the form of a grouping tree.
Inheritance Hierarchy

Remarks

The hierarchy is represented as a tree where group nodes are the parents of the nodes they contain. Group nodes can contain both normal nodes and other group nodes, and all top-level nodes are children of a virtual root node.

This class caches the hierarchical structure of the graph when instantiated. Therefore, subsequent modifications to the graph may not be reflected in the current instance.

When group nodes are copied or replaced, the original hierarchy should be restored by calling the restore method to avoid inconsistencies.

The following example shows a hierarchical graph containing group nodes, illustrating how nodes are nested inside group nodes:

The figure below shows the tree representing the hierarchical structure of the grouped graph. The labels in the hierarchy tree correspond to nodes from the grouped graph, and group nodes are treated as the parents of their contents.

This class cannot be instantiated

See Also

Developer's Guide

Members

No filters for this type

Properties

root

: LayoutNode
readonly
Gets the virtual root of the hierarchy tree, which is null.
The virtual root is used as the parent of all top-level nodes in the hierarchy tree. It can be passed to getChildren to obtain the top-level nodes.
readonlyfinal

Property Value

The virtual root of the hierarchy tree, which is null.

See Also

API
getChildren

Methods

clearGrouping

(): boolean
Clears all grouping information from the current LayoutGraphGrouping.
In most cases, it is better to use hideGrouping to temporarily hide the grouping, or replaceGrouping to replace it with a different hierarchy. This method is usually not required unless a complete reset of the grouping is desired. If this is a read-only view of the grouping, clearing may not be possible.
Note that the graph keeps being considered isGrouped.
final

Return Value

boolean
true if clearing was successful, otherwise false.

Throws

Exception ({ name: 'InvalidOperationError' })
Thrown if the current grouping hierarchy is a read-only view.

getChildren

(parent: LayoutNode): ILinkedItemEnumerable<LayoutNode>
Returns the direct children of the specified group node.
If root is passed as the parent node, the top-level nodes of the hierarchy are returned.
final

Parameters

parent: LayoutNode
The group node whose children are to be retrieved.

Return Value

ILinkedItemEnumerable<LayoutNode>
The child nodes of the specified parent.

Sample Graphs

ShownSetting: The marked nodes are children of group node 5 (grouped graph)

See Also

API
root, getParent, getDescendants

getDescendants

(parent: LayoutNode): ILinkedItemEnumerable<LayoutNode>
Returns all descendants of the given group node.
This method collects all nodes in the subtree rooted at the specified group node, traversing the hierarchy recursively. If the virtual root of the hierarchy tree is passed, the method returns all nodes in the graph.
final

Parameters

parent: LayoutNode
The group node for which to retrieve descendants. Passing the virtual root node will return all nodes in the graph.

Return Value

ILinkedItemEnumerable<LayoutNode>
A collection of nodes that belong to the subtree of the hierarchy tree rooted at the given parent.

Sample Graphs

ShownSetting: The marked nodes are descendants of group node 5 in the grouped graph.

See Also

API
getParent, getChildren

getNearestCommonAncestor

(node1: LayoutNode, node2: LayoutNode): LayoutNode
Returns the nearest common ancestor of the given nodes in the hierarchy.
The nearest common ancestor is the root of the smallest subtree that contains both nodes. If no common ancestor exists, the virtual root is returned. Special cases include:
  • node1 == node2: Returns the parent of node1/node2.
  • node1 is an ancestor of node2: Returns the parent of node1.
  • node2 is an ancestor of node1: Returns the parent of node2.
final

Parameters

node1: LayoutNode
One of the nodes to find the common ancestor for.
node2: LayoutNode
The other node to find the common ancestor for.

Return Value

LayoutNode
The nearest common ancestor node, or the virtual root if no common ancestor exists.

Sample Graphs

ShownSetting: The nearest common ancestor of nodes 1 and 2 is group node 5 (grouped graph).

getParent

(node: LayoutNode): LayoutNode
Returns the parent of the specified node.
The parent is the containing group node. If the node is a top-level node, it has no parent.
final

Parameters

node: LayoutNode
The node for which the parent is determined.

Return Value

LayoutNode
The parent of the given node, or null if the node is top-level.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if the given node is null.

See Also

API
setParent, getChildren, getDescendants, getNearestCommonAncestor

getRepresentative

(node: LayoutNode, group: LayoutNode): LayoutNode
Returns the immediate child of a group node that represents the given node.
If the node is already a child of the group node, the group node will be its representative. If the node is located further down the hierarchy, the method returns the child of the group node that is an ancestor of the node. If the node is not a descendant of the group, no representative is found.
final

Parameters

node: LayoutNode
The node for which to search for a representative.
group: LayoutNode
The group node to which the representative should belong.

Return Value

LayoutNode
The representative node or null if no representative exists.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if the provided node is null.

Sample Graphs

ShownSetting: Node 4 is the representative for node 2 in group node 5 (grouped graph)

hasChildren

(node: LayoutNode): boolean
Determines whether the specified group node has children as per the initial layout grouping.

While normal nodes never have children, group nodes may contain one or more child nodes.

This method checks for children that were part of the group node when the LayoutGraphGrouping was initially created. Note that the current structure of the graph may have changed, so this method reflects only the original layout grouping and not any modifications made afterward.

final

Parameters

node: LayoutNode
The node to check if it has children.

Return Value

boolean
true if the node has children; otherwise, false.

See Also

API
getChildren, isGroupNode

hasParent

(node: LayoutNode): boolean
Determines whether the specified node has a parent.
Returns true if the node is contained within a group node, otherwise false.
final

Parameters

node: LayoutNode
The node to check.

Return Value

boolean
true if the node has a parent; otherwise, false.

isGroupNode

(node: LayoutNode): boolean
Determines whether the specified node is a group node.
Group nodes can contain other nodes as children, whereas normal nodes never have children.
final

Parameters

node: LayoutNode
The node to check if it is a group node.

Return Value

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

See Also

API
hasChildren

isNormalEdge

(edge: LayoutEdge): boolean
Determines whether the given edge is a normal edge, as opposed to an edge that crosses any group node boundaries.
A normal edge connects nodes that are at the same hierarchy level and share the same parent node.
final

Parameters

edge: LayoutEdge
The edge to check.

Return Value

boolean
true if the given edge is normal; otherwise, false.

restore

()
Disposes of all internal data structures held by this LayoutGraphGrouping instance and restores the original grouping structure.
After disposal, this instance becomes unusable. For subsequent read-only group handling, use createReadOnlyView. If further changes are required to the hierarchy, a new LayoutGraphGrouping must be created using replaceGrouping or copyGrouping.
final

setIsGroupNode

(node: LayoutNode, isGroup: boolean)
Sets the group node state of the specified node.
This method designates whether the given node is a group node. Group nodes can contain children, while normal nodes cannot.
final

Parameters

node: LayoutNode
The node whose group node state will be set.
isGroup: boolean
A boolean indicating whether the node should be a group node (true) or a normal node (false).

Throws

Exception ({ name: 'ArgumentError' })
Thrown if node is the virtual root node.
Exception ({ name: 'InvalidOperationError' })
Thrown if isGroup is false and the node still has child nodes or if the current grouping hierarchy is a read-only view.

setParent

(node: LayoutNode, parent: LayoutNode)
Sets the parent for the specified node.
The parent is the group node that contains the specified node. If parent is null, the node becomes a top-level node.
final

Parameters

node: LayoutNode
The node for which the parent will be set.
parent: LayoutNode
The group node to set as the parent of the node, or null to make the node a top-level node.

Throws

Exception ({ name: 'ArgumentError' })
Thrown if the given node is null.
Exception ({ name: 'InvalidOperationError' })
Thrown if the current grouping hierarchy is a read-only view.

Static Methods

copyGrouping

(graph: LayoutGraph): LayoutGraphGrouping
static
Replaces the current grouping hierarchy of the specified graph with a new one, based on the current isGrouped and getParent relationships.

The old grouping hierarchy should be restored by calling the restore method on the returned LayoutGraphGrouping instance when the copy is no longer needed.

This method can be useful for ensuring that grouping information can be modified or reset to its original state, allowing for easy disposal of intermediate changes to the hierarchy.

The original (replaced) grouping hierarchy does not recognize changes made by the newly created instance, whereas the created instance is aware of changes made directly to the original grouping.

Copying the grouping pushes a context layer on the LayoutGraphContext stack and restoring it removes the layer. As such, the grouping can only be restored, when the context layer at the time of creation is the current top layer.
static

Parameters

graph: LayoutGraph
The graph for which the hierarchy is copied.

Return Value

LayoutGraphGrouping
A new instance of LayoutGraphGrouping that represents the copied grouping hierarchy, and allows the restoration of the previous hierarchy.

createReadOnlyView

(graph: LayoutGraph): LayoutGraphGrouping
static
Creates a read-only view of the current grouping hierarchy of the graph.
The created instance is read-only and should only be used for querying the current grouping status of the graph.
static

Parameters

graph: LayoutGraph
The LayoutGraph to create a read-only view for.

Return Value

LayoutGraphGrouping
A new read-only LayoutGraphGrouping instance.

hideGrouping

(graph: LayoutGraph): RestoreToken
static
Temporarily hides the current grouping hierarchy of the graph.

After calling this method, isGrouped will return false.

The hidden hierarchy can be restored by using the returned RestoreToken.

static

Parameters

graph: LayoutGraph
The LayoutGraph whose grouping hierarchy will be hidden.

Return Value

RestoreToken
A RestoreToken that can be used to restore the original hierarchy.

isFlat

(graph: LayoutGraph): boolean
static
Determines whether the given graph is flat.
A graph is flat if no group nodes exist or if all group nodes are empty, meaning they have no children.
static

Parameters

graph: LayoutGraph
The graph to check.

Return Value

boolean
true if the graph is flat; otherwise, false.

See Also

API
isGrouped

isGrouped

(graph: LayoutGraph): boolean
static
Determines whether the given graph is grouped.
A graph is considered grouped if any node is marked as a group node or has been assigned a parent node using setParent.
static

Parameters

graph: LayoutGraph
The graph to check.

Return Value

boolean
true if the graph contains hierarchical information, otherwise false.

See Also

API
isFlat

replaceGrouping

(
graph: LayoutGraph
isGroupNode?: function(LayoutNode): boolean
getParent?: function(LayoutNode): LayoutNode
): LayoutGraphGrouping
static
Replaces the existing grouping hierarchy of the graph with a new hierarchy, optionally using the provided isGroupNode and getParent callbacks to define the new hierarchy.

The old grouping hierarchy can be restored by calling the restore method on the returned LayoutGraphGrouping instance.

If both isGroupNode and getParent are null, the new grouping hierarchy will be empty and all nodes are top-level.

The original (replaced) grouping hierarchy does not recognize changes made by the newly created instance, whereas the created instance is aware of changes made directly to the original grouping.

Replacing the grouping pushes a context layer on the LayoutGraphContext stack and restoring it removes the layer. As such, the grouping can only be restored when the context layer at the time of creation is the current top layer.
static

Parameters

graph: LayoutGraph
The LayoutGraph whose grouping hierarchy will be replaced.
isGroupNode?: function(LayoutNode): boolean
An optional callback to determine if a node should be treated as a group node.
getParent?: function(LayoutNode): LayoutNode
An optional callback that returns the parent node for a given node or null if the node is top-level.

Return Value

LayoutGraphGrouping
A new LayoutGraphGrouping instance that can restore the original hierarchy.