Grouping

class GroupingManager(graphEditor)

Class managing all node groups.

Arguments:

  • graphEditor (default) –

Returns:

GroupingManager –

GroupingManager.addNodeToGroup(groupId, nodeId, atPosition, eventSource=EventSource.API, sourceEvent)

Add a node to a group.

For the group behaviour to work correctly both the groupId and the nodeId schould correspond to an existing node in the grapheditor.

This method checks if adding nodeId to the group would create a cycle in the group graph by using getAllChildrenOf . It also checks if nodeId == groupId and aborts if true.

The method updates the group depths of all affected groups recursively.

If the parent group is part of a tree and the child group is not part of a tree the child group is added to the parents tree.

The ‘groupjoin’ event is the last event dispatched by this method. The afterGroupJoin callback of the parent group behaviour is called after the ‘groupjoin’ event was dispatched.

Arguments:

  • groupId (string|number) –

  • nodeId (string|number) –

  • atPosition (Point) –

  • eventSource (EventSource) –

  • sourceEvent (Event) –

Returns:

boolean –

GroupingManager.clearAllGroups()

Clears all group information stored in this GroupingManager instance.

Can be useful when redrawing/resetting the graph.

GroupingManager.derefGraph()

Safely deref the grapheditor weak reference.

Returns:

default –

GroupingManager.getAllChildrenOf(groupId)

Get a set of all children of a group including children of children.

Arguments:

  • groupId (string|number) –

Returns:

Set<string> –

GroupingManager.getAllRegisteredGroups()

Get all known group ids.

Use getGroupForNode or getGroupBehaviourOf to get more information about the groups.

Returns:

Set<string> –

GroupingManager.getCanDraggedNodeLeaveGroup(groupId, childGroupId, childNode)

Check if the node is allowed to leave its group.

Arguments:

  • groupId (string|number) –

  • childGroupId (string|number) –

  • childNode (Node) –

Returns:

boolean –

GroupingManager.getChildrenOf(groupId)

Get the set of direct children of this group.

Do NOT alter this set!

Arguments:

  • groupId (string|number) –

Returns:

Set<string> –

GroupingManager.getGroupBehaviourOf(groupId)

Get the group behaviour of a specific group.

The returned group behaviour will always have at least the default implementations for captureThisDraggedNode , afterNodeJoinedGroup , afterNodeLeftGroup and beforeNodeMove set.

The returned group behaviour may be null if the group id was never used before.

Arguments:

  • groupId (string|number) –

Returns:

GroupBehaviour –

GroupingManager.getGroupCapturingDraggedNode(groupId, childGroupId, groupNode, node)

Get the group that the (dragged) node may join into.

Only groups in the tree as groupId (including groupId) may capture the (dragged) node.

Joining a group returned by this method does not create a cycle in the group graph!

If two or more groups in the path to the tree root may capture the (dragged) node the group closest to the groupNode is returned.

Arguments:

  • groupId (string|number) –

  • childGroupId (string|number) –

  • groupNode (Node) –

  • node (Node) –

Returns:

string –

GroupingManager.getGroupCapturingIncomingEdge(child)

Get the id of the group that will capture incoming edges of the given node.

Only groups in the same tree that have this node as a direct or indirect child may capture its incoming edges.

If two or more groups in the path to the tree root may capture its incoming edges the group closest to the node is returned.

Arguments:
Returns:

string –

GroupingManager.getGroupCapturingMovementOfChild(child)

Get the id of the group that will capture the movement of the given node.

Only groups in the same tree that have this node as a direct or indirect child may capture its movement.

If two or more groups in the path to the tree root may capture the node movement the group closest to the tree root is returned.

Arguments:
Returns:

string –

GroupingManager.getGroupCapturingOutgoingEdge(child)

Get the id of the group that will capture outgoing edges of the given node.

Only groups in the same tree that have this node as a direct or indirect child may capture its outgoing edges.

If two or more groups in the path to the tree root may capture its outgoing edges the group closest to the node is returned.

Arguments:
Returns:

string –

GroupingManager.getGroupDepthOf(groupId)

Get the depth of the group in the directed acyclic graph.

A group with no parents has a depth of 0 . A group with parents has a depth of max(parent => parent.depth) + 1 .

This can be useful for sorting the nodes so that children of a group appear above the group. See also GraphEditor.onBeforeCompleteRender .

Arguments:

  • groupId (string|number) –

Returns:

number –

GroupingManager.getGroupForNode(nodeId)

Get a NodeGroup object for the given id.

If the groupsById does not contain a group with that id a new NodeGroup with a default GroupBehaviour is created.

Arguments:

  • nodeId (string|number) –

Returns:

NodeGroup –

GroupingManager.getParentsOf(groupId)

Get the set of direct parents of this group.

Do NOT alter this set!

Arguments:

  • groupId (string|number) –

Returns:

Set<string> –

GroupingManager.getTreeDepthOf(groupId)

Get the depth of the group in the tree.

The tree root has a depth of 0 . All other nodes of the tree have a depth of treeParent.depth + 1 .

Arguments:

  • groupId (string|number) –

Returns:

number –

GroupingManager.getTreeParentOf(groupId)

Get the tree parent of the group.

The tree parent is always a parent of the group too. If the group is the tree root then it will not have a tree parent!

Arguments:

  • groupId (string|number) –

Returns:

string –

GroupingManager.getTreeRootOf(groupId)

Get the tree root of the group.

All groups with the same tree root are part of the same tree.

Arguments:

  • groupId (string|number) –

Returns:

string –

GroupingManager.joinTreeOfParent(groupId, treeParentId, eventSource=EventSource.API, sourceEvent)

Let the group join the tree of one of its parents.

If the given parent is not part of a tree calling this method has the same result as calling leaveTree .

If the group is already part of a tree the group will leave this tree before joining the tree of the parent. Use markAsTreeRoot on the parent befor joining its tree if the parent is not part of a tree yet.

Arguments:

  • groupId (string|number) –

  • treeParentId (string|number) –

  • eventSource (EventSource) –

  • sourceEvent (Event) –

Returns:

boolean –

GroupingManager.leaveTree(groupId, eventSource=EventSource.API, sourceEvent)

Remove the group from its tree.

This method sets all tree related attributes of the group and all its (recursive) children that are part of the same tree to null.

This method does not remove the group from any group it is currently a child of!

Arguments:

  • groupId (string|number) –

  • eventSource (EventSource) –

  • sourceEvent (Event) –

GroupingManager.markAsTreeRoot(groupId, eventSource=EventSource.API, sourceEvent)

Make an existing group into a tree root.

This method will make an existing group that is not part of a tree into a tree root. All children of this group that are not part of a tree will join the tree defined by the newly created tree root.

Arguments:

  • groupId (string|number) –

  • eventSource (EventSource) –

  • sourceEvent (Event) –

Returns:

boolean –

GroupingManager.removeNodeFromGroup(groupId, nodeId, eventSource=EventSource.API, sourceEvent)

Remove a node from a group.

This method will only remove direct children from a group!

If the node is part of another group that is in the same tree it will set its tree parent to that group instead of leaving the tree. If more than one parent is part of the tree the parent with the smallest treeDepth (closest to the root) is chosen.

The ‘groupleave’ event is the last event dispatched by this method. The afterGroupLeave callback of the parent group behaviour is called after the ‘groupleave’ event was dispatched.

Arguments:

  • groupId (string|number) –

  • nodeId (string|number) –

  • eventSource (EventSource) –

  • sourceEvent (Event) –

Returns:

boolean –

GroupingManager.setGroupBehaviourOf(groupId, groupBehaviour)

Set the graoup behaviour.

The default implementations for captureThisDraggedNode , afterNodeJoinedGroup ,

afterNodeLeftGroup and beforeNodeMove will be inserted into the given groupBehaviour

if the behaviour does not specify them already.

Arguments:

NodeGroup

Note

These classes are only used internally by the GroupingManager!

class TreeInformation()

Interface for tree information containing the root of the tree, the direct tree parent and the depth of this group.

interface

TreeInformation.treeDepth

type: number

The depth of the group in the tree. The tree root has depth 0.

TreeInformation.treeParent

type: string

The parent group id of this group. The tree root has no parent.

TreeInformation.treeRoot

type: string

The root (group id) of the tree. The tree root has itself as the tree root.

class NodeGroup(nodeId)

Class containing all information of a group.

This class is not intended to be used outside of the GroupingManager!

Implements:
Arguments:

  • nodeId (string) –

Returns:

NodeGroup –

NodeGroup.children

type: Set<string>

A set of all direct children (group ids).

NodeGroup.groupBehaviour

type: GroupBehaviour

The group behaviour that determines how this group acts.

NodeGroup.groupDepth

type: number

The depth of the group in the acyclic directed group graph. Initialized as 0. Max(parents => parents.depth) + 1

NodeGroup.groupId

type: string

The id of this group. This should be the same id as the node it represents.

NodeGroup.parents

type: Set<string>

A set of all direct parents (group ids).

NodeGroup.treeDepth

type: number

The depth of the group in the tree. Initialized as 0. treeParent.treeDepth + 1

NodeGroup.treeParent

type: string

The parent that has the same tree root as this group that should be considered the parent for this group and this tree.

NodeGroup.treeRoot

type: string

The root of the tree this group belongs to. Null if the group is not part of a tree.

GroupBehaviour

class GroupBehaviour()

Interface describing the behaviour of a NodeGroup.

interface

GroupBehaviour.afterNodeJoinedGroup?

type: (group: string, childGroup: string, groupNode: Node, childNode: Node, graphEditor: default, atPosition: Point) => void

Callback called after the childGroup has joined the parent group.

Default implementation: defaultAfterNodeJoinedGroup

GroupBehaviour.afterNodeLeftGroup?

type: (group: string, childGroup: string, groupNode: Node, childNode: Node, graphEditor: default) => void

Callback called after the childGroup has left the parent group.

Default implementation: defaultAfterNodeLeftGroup

GroupBehaviour.allowDraggedNodesLeavingGroup?

type: boolean

If true dragged nodes can generally leave this group.

GroupBehaviour.allowFreePositioning?

type: boolean

If true always allow free positioning of child nodes inside the group. (Always true if the node has no defined drop zones.)

GroupBehaviour.allowThisDraggedNodeLeavingGroup?

type: GroupBehaviourDecisionCallback

Decide whether this specific node may leave this group.

GroupBehaviour.beforeNodeMove?

type: (group: string, childGroup: string, groupNode: Node, childNode: Node, newPosition: Point, graphEditor: default) => boolean|void

Callback called before a direct child in the same tree is moved to a new position.

Default implementation: defaultBeforeNodeMove

GroupBehaviour.captureChildMovement?

type: boolean

If true this group captures all movement events for nodes in the same tree. A captured movement event acts as if the node of this group is moved instead of the original target.

The group and children must be part of the same tree for this to work!

GroupBehaviour.captureChildMovementForNode?

type: GroupBehaviourDecisionCallback

Decide whether to capture the movement event from this particular node.

The default is () => true

GroupBehaviour.captureDraggedNodes?

type: boolean

If true dragged nodes can generally join this group.

GroupBehaviour.captureIncomingEdges?

type: boolean

If true this group captures all incoming dragged edges of child nodes (including transitive children) in the same tree. A captured edge behaves as if it is targeting this group’s node.

The group and children must be part of the same tree for this to work!

GroupBehaviour.captureIncomingEdgesForNode?

type: GroupBehaviourDecisionCallback

Decide whether to capture the incoming dragged edge from this particular node.

The default is () => true

GroupBehaviour.captureOutgoingEdges?

type: boolean

If true this group captures all outgoing dragged edges of child nodes (including transitive children) in the same tree. A captured edge behaves as if it is dragged from this group’s node.

The group and children must be part of the same tree for this to work!

GroupBehaviour.captureOutgoingEdgesForNode?

type: GroupBehaviourDecisionCallback

Decide whether to capture the outgoing dragged edge from this particular node.

The default is () => true

GroupBehaviour.captureThisDraggedNode?

type: GroupBehaviourDecisionCallback

Decide whether this specific node may join this group.

Default implementation: defaultCaptureThisDraggedNode

GroupBehaviour.childNodePositions?

type: Map<string, string|Point>

A map containing the positions of nodes inside the group.

The position can either be the id of a drop zone (string) or a point relative to the node of the group. For drop zones the center of the bounding box is the position the node will be placed.

A node with a position in this map will not move from this position by dragging or calling moveNode! Delete the node id from this map to allow free movement for the node.

GroupBehaviour.delegateIncomingEdgeTargetToNode?

type: GroupBehaviourEdgeDelegationCallback

Delegate an incoming edge from this group to another node. A delegated edge behaves as if target is the given node.

The default is to not change the current target.

GroupBehaviour.delegateOutgoingEdgeSourceToNode?

type: GroupBehaviourEdgeDelegationCallback

Delegate an outgoing edge from this group to another node. A delegated edge behaves as if it is dragged from the given node.

The default is to not change the current source.

GroupBehaviour.moveChildrenAlongGoup?

type: boolean

If true all children (including transitive children) will move the same amount as the group.

GroupBehaviour.occupiedDropZones?

type: Map<string, string>

A map mapping the id of occupied drop zones to the id of the node occupying them.

GroupBehaviour.onNodeMoveEnd?

type: (group: string, childGroup: string, groupNode: Node, childNode: Node, graphEditor: default) => boolean|void

Callback called after a direct child in the same tree finished moving.

This will not be called if the node left the group while moving!

GroupBehaviour.onNodeMoveStart?

type: (group: string, childGroup: string, groupNode: Node, childNode: Node, graphEditor: default) => boolean|void

Callback called before a direct child in the same tree is moved.

This will not be called if the node joins the group while moving!

GroupBehaviourDecisionCallback(group, childGroup, groupNode, childNode, graphEditor)

A function that given a group, a (candidate) child group and the corresponding nodes decides if a certain action can be done.

Arguments:

  • group (string) – the group id of this group

  • childGroup (string) – the group id of the group (or node) the action will be performed for

  • groupNode (Node) – the node in the grapheditor with the same id as group, may be null.

  • childNode (Node) – the node in the grapheditor with the same id as childGroup, may be null.

  • graphEditor (GraphEditor) – the instance of the grapheditor.

Returns:

boolean – true iff the action should be performed.

GroupBehaviourEdgeDelegationCallback(group, groupNode, edge, graphEditor)

A function that given a group, the corresponding node and an edge decides which node should handle the edge.

Arguments:

  • group (string) – the group id of this group

  • groupNode (Node) – the node in the grapheditor with the same id as group, may be null.

  • edge (Edge) – the (incoming or outgoing) edge

  • graphEditor (GraphEditor) – the instance of the grapheditor.

Returns:

string – the id of an existing Node that should handle this edge (as its source or target)

Default Implementations for GroupBehaviour

defaultCaptureThisDraggedNode(this, group, childGroup, groupNode, childNode, graphEditor)

Default behaviour of the captureThisDraggedNode GroupBehaviourDecisionCallback of a GroupBehaviour.

If the group behaviour has allowFreePositioning set as true then this method always returns true.

This method rerturns true if the group node has an unoccupied dropzone that allows the type of the childNode in its filters.

If the dropzone is already marked as occupied by the same id as the childNode the dropzone is not considered occupied by this method!

Arguments:

  • this (GroupBehaviour) –

  • group (string) –

  • childGroup (string) –

  • groupNode (Node) –

  • childNode (Node) –

  • graphEditor (default) –

Returns:

boolean –

defaultBeforeNodeMove(this, group, childGroup, groupNode, childNode, newPosition, graphEditor)

Default behaviour of the beforeNodeMove callback of a GroupBehaviour.

If both groupNode and childNode are not null and the groupNode has dropzones this method places the childNode at the nearest unoccupied dropzone.

This method only considers dropzones with a filter allowing the type of the childNode.

This method uses (and creates) the occupiedDropZones map and the childNodePositions of the groupBehaviour.

The nearest dropzone is determined by the distance of the dropzone center to the coordinates of the childNode.

If the childNode was already occupying a dropZone it will still change to a nearer dropzone when moved.

Arguments:

  • this (GroupBehaviour) –

  • group (string) –

  • childGroup (string) –

  • groupNode (Node) –

  • childNode (Node) –

  • newPosition (Point) –

  • graphEditor (default) –

defaultAfterNodeJoinedGroup(this, group, childGroup, groupNode, childNode, graphEditor, atPosition)

Default behaviour of the afterNodeJoinedGroup callback of a GroupBehaviour.

This method calls beforeNodeMove of the GroupBehaviour.

This method assumes beforeNodeMove to be implemented by defaultBeforeNodeMove . If beforeNodeMove has a different behaviour than the default implementation then this method should also be replaced by a custom method!

Arguments:

  • this (GroupBehaviour) –

  • group (string) –

  • childGroup (string) –

  • groupNode (Node) –

  • childNode (Node) –

  • graphEditor (default) –

  • atPosition (Point) –

defaultAfterNodeLeftGroup(this, group, childGroup, groupNode, childNode, graphEditor)

Default behaviour of the afterNodeLeftGroup callback of a GroupBehaviour.

This method removes childNodePositions for the node that left and frees all dropzones that were occupied by the node that left.

Arguments:

  • this (GroupBehaviour) –

  • group (string) –

  • childGroup (string) –

  • groupNode (Node) –

  • childNode (Node) –

  • graphEditor (default) –