# Class Group

GoJS® Diagramming Components
version 3.0.13
by Northwoods Software®

#### Hierarchy

- Node
  - Group

A Group is a Node that can contain a subgraph of Nodes and Links, which are members of the group.

For more discussion, see Introduction to Groups. See samples that make use of Groups in the samples index.

Although you can create a Group and Diagram.add it to a Diagram, this does not update the Model. It is more common to create a group by adding a node data object to the model by calling Model.addNodeData. For example:

      myDiagram.startTransaction("make new group");
      myDiagram.model.addNodeData({ key: "Omega", isGroup: true });
      myDiagram.commitTransaction("make new group");

This will cause a Group to be created (copying the template found in Diagram.groupTemplateMap), added to the Diagram in some Layer (based on Part.layerName), and bound to the group data (resulting in Panel.data referring to that group data object). Note that the JavaScript object includes setting `isGroup` to true, to indicate that the object represents a Group rather than a regular Node or simple Part.

The member Parts of a Group, which you can access as the memberParts collection, belong to the group but are not in the visual tree of the group. All Parts are directly in Layers -- they cannot be inside a Panel. This allows group member parts to be in layers different from the group's layer.

You can change the membership of a Node or a simple Part in a Group by setting its Part.containingGroup property. This is done automatically for you by the diagram if you initialize the `group` property on the node data in the model to be the key of the containing group node data. Thus you should do something like:

      myDiagram.startTransaction("add new member");
      myDiagram.model.addNodeData({ group: someExistingGroupKey, ... });
      myDiagram.commitTransaction("add new member");

where you would make sure the node data object included all of the properties you need. You can also change the relationship dynamically by calling GraphLinksModel.setGroupKeyForNodeData.

The membership of Links is computed automatically for you by the diagram based on the membership of the connected Nodes. For example, if the Link.fromNode is a top-level node but the Link.toNode is a member of a group, the link is a top-level link. If the two connected nodes both belong to the same group, the link is a member of that group. If the two connected nodes belong to different groups, the link belongs to the common container group, if there is any. Note that if a link connects a member of a group with the group itself, the link is a member of that group.

All of the group-member relationships effectively form a tree structure. These properties and methods are useful in navigating these relationships:

- Part.containingGroup
- Part.isTopLevel
- Part.findTopLevelPart
- Part.findSubGraphLevel
- Part.findCommonContainingGroup
- memberParts
- findSubGraphParts
- findExternalLinksConnected
- findExternalNodesConnected

As the membership of a group changes, you may want to update the appearance of the group. You can set the memberAdded and memberRemoved properties to be functions that are called. These functions must not modify any membership relationships -- these function properties just exist to update the appearance of the Group.

You can control whether certain Nodes are added to a Group by CommandHandler.groupSelection or addMembers or CommandHandler.addTopLevelParts by affecting the result of CommandHandler.isValidMember, which is responsible for deciding whether it is OK to add a Node to a Group or to remove a Node from a Group to be a top-level node. You can override that predicate on CommandHandler, but it is easier to set the memberValidation or CommandHandler.memberValidation functional property.

For a more general discussion of validation, see Introduction to Validation.

The area occupied by the subgraph is represented in the group's visual tree by a Placeholder. As the group placeholder grows and shrinks based on the sizes and positions of the member nodes and links, the group will grow and shrink accordingly. The placeholder is always the Part.locationObject, although you may specify any Spot as the Part.locationSpot. A Group need not have a placeholder, but it may have at most one.

A group has its own layout property that is used to position the member nodes and route the member links.

The Group class also supports the notion of expanding and collapsing the subgraph, causing the member nodes and links to be shown or hidden. Principally this is a matter of setting isSubGraphExpanded. Changes to this property will result in calls to collapseSubGraph or expandSubGraph, as appropriate.

If you want to change the appearance of the group you can do so in a function that you assign to the subGraphExpandedChanged property. This function must not modify any member relationships or expand or collapse any groups -- the functional property just exists to update the appearance of the Group.

For more discussion and examples, see SubGraphs.

If you want the user to be able to create a Group out of the currently selected Parts using the CommandHandler.groupSelection command, you need to first set the CommandHandler.archetypeGroupData property to a data object with `isGroup` set to true. If you want the user to be able to ungroup a Group, using the CommandHandler.ungroupSelection command, you need to set ungroupable to true.

For more discussion and examples, see Groups, SubGraphs, and Sized Groups.

Only Groups that are in Diagrams can have member Parts or connections via Links. Templates should not be connected with Links, be labels of Links, be members of Groups, have any member Parts, or have any Adornments.

#####
Index

### Constructors

constructor

### Accessors

computesBoundsAfterDrag
computesBoundsIncludingLinks
computesBoundsIncludingLocation
handlesDragDropForMembers
isSubGraphExpanded
layout
memberAdded
memberParts
memberRemoved
memberValidation
placeholder
subGraphExpandedChanged
ungroupable
wasSubGraphExpanded

### Methods

addMembers
canAddMembers
canUngroup
collapseSubGraph
expandSubGraph
findExternalLinksConnected
findExternalNodesConnected
findSubGraphParts
move

#####
Inherited Index

### Accessors

GraphObject.actionCancel
GraphObject.actionDown
GraphObject.actionMove
GraphObject.actionUp
GraphObject.actualBounds
GraphObject.alignment
GraphObject.alignmentFocus
GraphObject.angle
GraphObject.background
GraphObject.click
GraphObject.column
GraphObject.columnSpan
GraphObject.contextClick
GraphObject.contextMenu
GraphObject.cursor
GraphObject.desiredSize
GraphObject.doubleClick
GraphObject.enabledChanged
GraphObject.fromEndSegmentLength
GraphObject.fromLinkable
GraphObject.fromLinkableDuplicates
GraphObject.fromLinkableSelfNode
GraphObject.fromMaxLinks
GraphObject.fromShortLength
GraphObject.fromSpot
GraphObject.height
GraphObject.isActionable
GraphObject.isPanelMain
GraphObject.margin
GraphObject.maxSize
GraphObject.measuredBounds
GraphObject.minSize
GraphObject.mouseDragEnter
GraphObject.mouseDragLeave
GraphObject.mouseDrop
GraphObject.mouseEnter
GraphObject.mouseHold
GraphObject.mouseHover
GraphObject.mouseLeave
GraphObject.mouseOver
GraphObject.name
GraphObject.naturalBounds
GraphObject.opacity
GraphObject.panel
GraphObject.part
GraphObject.pickable
GraphObject.portId
GraphObject.position
GraphObject.row
GraphObject.rowSpan
GraphObject.scale
GraphObject.segmentFraction
GraphObject.segmentIndex
GraphObject.segmentOffset
GraphObject.segmentOrientation
GraphObject.shadowVisible
GraphObject.stretch
GraphObject.toEndSegmentLength
GraphObject.toLinkable
GraphObject.toLinkableDuplicates
GraphObject.toLinkableSelfNode
GraphObject.toMaxLinks
GraphObject.toShortLength
GraphObject.toSpot
GraphObject.toolTip
GraphObject.visible
GraphObject.width
Node.avoidable
Node.avoidableMargin
Node.isLinkLabel
Node.isTreeExpanded
Node.isTreeLeaf
Node.isTreeRoot
Node.labeledLink
Node.linkConnected
Node.linkDisconnected
Node.linkValidation
Node.linksConnected
Node.port
Node.portSpreading
Node.ports
Node.treeExpandedChanged
Node.wasTreeExpanded
Panel.alignmentFocusName
Panel.columnCount
Panel.columnSizing
Panel.data
Panel.defaultAlignment
Panel.defaultColumnSeparatorDashArray
Panel.defaultColumnSeparatorStroke
Panel.defaultColumnSeparatorStrokeWidth
Panel.defaultRowSeparatorDashArray
Panel.defaultRowSeparatorStroke
Panel.defaultRowSeparatorStrokeWidth
Panel.defaultSeparatorPadding
Panel.defaultStretch
Panel.elements
Panel.graduatedMax
Panel.graduatedMin
Panel.graduatedRange
Panel.graduatedTickBase
Panel.graduatedTickUnit
Panel.gridCellSize
Panel.gridOrigin
Panel.isClipping
Panel.isEnabled
Panel.isOpposite
Panel.itemArray
Panel.itemCategoryProperty
Panel.itemIndex
Panel.itemTemplate
Panel.itemTemplateMap
Panel.leftIndex
Panel.padding
Panel.rowCount
Panel.rowSizing
Panel.topIndex
Panel.type
Panel.viewboxStretch
Part.adornments
Part.category
Part.containingGroup
Part.containingGroupChanged
Part.copyable
Part.deletable
Part.diagram
Part.dragComputation
Part.groupable
Part.highlightedChanged
Part.isAnimated
Part.isHighlighted
Part.isInDocumentBounds
Part.isLayoutPositioned
Part.isSelected
Part.isShadowed
Part.isTopLevel
Part.key
Part.layer
Part.layerChanged
Part.layerName
Part.layoutConditions
Part.location
Part.locationObject
Part.locationObjectName
Part.locationSpot
Part.maxLocation
Part.minLocation
Part.movable
Part.reshapable
Part.resizable
Part.resizeAdornmentTemplate
Part.resizeCellSize
Part.resizeObject
Part.resizeObjectName
Part.rotatable
Part.rotateAdornmentTemplate
Part.rotateObject
Part.rotateObjectName
Part.rotationSpot
Part.selectable
Part.selectionAdorned
Part.selectionAdornmentTemplate
Part.selectionChanged
Part.selectionObject
Part.selectionObjectName
Part.shadowBlur
Part.shadowColor
Part.shadowOffset
Part.text
Part.textEditable
Part.zOrder

### Methods

GraphObject.apply
GraphObject.attach
GraphObject.bind
GraphObject.bindModel
GraphObject.bindObject
GraphObject.bindTwoWay
GraphObject.findBindingPanel
GraphObject.getDocumentAngle
GraphObject.getDocumentPoint
GraphObject.getDocumentScale
GraphObject.getLocalPoint
GraphObject.isContainedBy
GraphObject.isEnabledObject
GraphObject.isVisibleObject
GraphObject.set
GraphObject.setProperties
GraphObject.theme
GraphObject.themeData
GraphObject.themeModel
GraphObject.themeObject
GraphObject.trigger
Node.collapseTree
Node.expandTree
Node.findCommonTreeParent
Node.findExternalTreeLinksConnected
Node.findLinksBetween
Node.findLinksConnected
Node.findLinksInto
Node.findLinksOutOf
Node.findLinksTo
Node.findNodesConnected
Node.findNodesInto
Node.findNodesOutOf
Node.findPort
Node.findTreeChildrenLinks
Node.findTreeChildrenNodes
Node.findTreeLevel
Node.findTreeParentChain
Node.findTreeParentLink
Node.findTreeParentNode
Node.findTreeParts
Node.findTreeRoot
Node.findVisibleNode
Node.getAvoidableRect
Node.isInTreeOf
Panel.add
Panel.addColumnDefinition
Panel.addRowColumnDefinition
Panel.addRowDefinition
Panel.copy
Panel.copyTemplate
Panel.elt
Panel.findColumnForLocalX
Panel.findItemPanelForData
Panel.findMainElement
Panel.findObject
Panel.findRowForLocalY
Panel.getColumnDefinition
Panel.getRowDefinition
Panel.graduatedPointForValue
Panel.graduatedValueForPoint
Panel.insertAt
Panel.rebuildItemElements
Panel.remove
Panel.removeAt
Panel.removeColumnDefinition
Panel.removeRowDefinition
Part.addAdornment
Part.canCopy
Part.canDelete
Part.canEdit
Part.canGroup
Part.canLayout
Part.canMove
Part.canReshape
Part.canResize
Part.canRotate
Part.canSelect
Part.clearAdornments
Part.findAdornment
Part.findCommonContainingGroup
Part.findSubGraphLevel
Part.findTopLevelPart
Part.getDocumentBounds
Part.invalidateLayout
Part.isMemberOf
Part.isVisible
Part.moveTo
Part.removeAdornment
Part.updateAdornments
Part.updateRelationshipsFromData
Part.updateTargetBindings

## Constructors

### constructor

- new Group(type?: string | PanelLayout, init?: Partial<Group>): Group

- Constructs an empty Group with no visual elements and no member parts; typically a Group will have some visual elements surrounding a Placeholder.

  The panel type must be a PanelLayout, such as Panel.Position). The string value such as "Auto" may also be used.

  Usage example:

      // Constructs a Group, sets properties on it,
      // adds a data binding to it,
      // and adds two GraphObjects to the Group:
      const g = new go.Group("Auto", {
          margin: 5,
          background: "red"
        })
        .add(
          new go.Shape("RoundedRectangle"),
          new go.TextBlock("Some Text")
        );

  #### Parameters

  - ##### `Optional` type: string | PanelLayout

    a string or PanelLayout, such as "Horizontal", Panel.Vertical. If not supplied, the default Panel type is "Position".

  - ##### `Optional` init: Partial<Group>

    Optional initialization properties.

  #### Returns Group

- new Group(init?: Partial<Group>): Group

- Constructs an empty Panel. Default type is Panel.Position.

  #### Parameters

  - ##### `Optional` init: Partial<Group>

    Optional initialization properties.

  #### Returns Group

## Accessors

### computesBoundsAfterDrag
: boolean

- Gets or sets whether the size of the area of the Group's placeholder should remain the same during a DraggingTool move until a drop occurs. Groups within temporary layers (such as new Groups during a drag-copy) are unaffected by this property.

  In other words, when the value is true, re-computing the bounds of the members is suspended until a drop occurs, at which time the border is recomputed, perhaps not including some members that had been dragged out and reparented. The initial value is false.

### computesBoundsIncludingLinks
: boolean

- Gets or sets whether a placeholder's bounds includes the bounds of member Links. The default value is true. If this is false, only non-Link member Parts are used to compute the Placeholder's bounds in document coordinates.

### computesBoundsIncludingLocation
: boolean

- Gets or sets whether a placeholder's bounds includes the previous Group.location. The default value is false.

### handlesDragDropForMembers
: boolean

- Gets or sets whether drag-and-drop events may be bubbled up to this Group if not handled by member Parts. The default value is false -- each Node or Link that is a member of the Group needs to define its own GraphObject.mouseDragEnter, GraphObject.mouseDragLeave, and GraphObject.mouseDrop event handlers if you want dragging/dropping on a member part to act as if the user were acting on the group.

  This is currently restricted to only call the mouseDragEnter, mouseDragLeave, and mouseDrop event handlers defined on the whole Group, not on any element inside the Group's visual tree.

### isSubGraphExpanded
: boolean

- Gets or sets whether the subgraph contained by this group is expanded. Changing this property's value will call collapseSubGraph or expandSubGraph, and also will call the value of subGraphExpandedChanged if it is a function.

  The initial value is true -- this group's member parts are shown.

  There is an analogous property for expanded/collapsed trees of Nodes and Links: Node.isTreeExpanded.

### layout
: Layout

- Gets or sets the Layout used to position all of the immediate member nodes and links in this group. By default this property is an instance of Layout -- no special layout is used, which just makes sure each member node has a valid location.

  A group layout must not be shared with any Diagram.layout.

### memberAdded
: ((thisGroup: Group, newPart: Part) => void)

- Gets or sets the function that is called after a member Part has been added to this Group. It is typically used to modify the appearance of the group. The first argument will be this Group. The second argument will be a Part, typically a Node, but may be a simple Part or a Link.

  If the value is a function, that function must not modify any membership relationships. The member Part has already been added -- trying to remove it or adding or removing another member or the Group itself may produce undefined behavior.

  The default value is null -- no function is called.

### `Readonly` memberParts
: Iterator<Part>

- This read-only property returns an iterator over the member Parts of this Group. Setting Part.containingGroup to refer to this Group will add that part to this collection. The Parts can be Nodes, Links, Groups, or simple Parts.

  A template should not have any member parts.

### memberRemoved
: ((thisGroup: Group, oldPart: Part) => void)

- Gets or sets the function that is called after a member Part has been removed from this Group. It is typically used to modify the appearance of the group. The first argument will be this Group. The second argument will be a Part, typically a Node, but may be a simple Part or a Link.

  If the value is a function, that function must not modify any membership relationships. The member Part has already been removed -- trying to add it or adding or removing another member or the Group itself may produce undefined behavior.

  The default value is null -- no function is called.

### memberValidation
: ((thisGroup: Group, part: Part) => boolean)

- Gets or sets the predicate that determines whether or not a Part may become a member of this group. If this is non-null, the predicate is called in addition to any CommandHandler.memberValidation predicate.

  The default predicate is null, which is equivalent to simply returning true. The first argument will be this Group. The second argument will be a Part, typically a Node, but will not be a Link or an Adornment.

  The function, if supplied, must not have any side-effects.

### `Readonly` placeholder
: Placeholder

- This read-only property returns a Placeholder that this group may contain in its visual tree. The value may be null if there is no Placeholder in the visual tree of this Group.

  There may be at most one Placeholder in a Group. The Placeholder determines the Part.location for the Group, when it is visible, and even when isSubGraphExpanded is false. When there is a Placeholder, the Part.locationObjectName is ignored and the Part.locationObject will be this Placeholder.

### subGraphExpandedChanged
: ((thisGroup: Group) => void)

- Gets or sets the function that is called when isSubGraphExpanded has changed value. The argument to that function will be this Group.

  If the value is a function, that function must not expand or collapse any groups. The Group has already been expanded or collapsed -- trying to change it again may produce undefined behavior.

  The default value is null -- no function is called.

### ungroupable
: boolean

- Gets or sets whether the user may ungroup this group. The initial value is false.

  `see`

  canUngroup

### wasSubGraphExpanded
: boolean

- Gets or sets whether the subgraph starting at this group had been collapsed by a call to expandSubGraph on the containing Group. The initial value is false.

  `see`

  isSubGraphExpanded

## Methods

### `Virtual` addMembers

- addMembers(coll: Iterable<Part>, check?: boolean): boolean

- Add the Parts in the given collection as members of this Group for those Parts for which CommandHandler.isValidMember returns true. If the check argument to this method is not supplied or false, this will set Part.containingGroup on each part unconditionally, not calling CommandHandler.isValidMember.

  The CommandHandler predicate will use CommandHandler.memberValidation and memberValidation, if either or both are defined.

  At this time there is no "removeMembers" method. If you want to make a collection of Parts to be top-level parts, not members of any Group but still in the Diagram, call CommandHandler.addTopLevelParts. If you want to remove a collection of Parts not only from a Group but from the whole Diagram, call Diagram.removeParts.

  #### Parameters

  - ##### coll: Iterable<Part>

  - ##### `Optional` check: boolean

    whether to call CommandHandler.isValidMember to confirm that it is valid to add the Part to be a member of this Group.

  #### Returns boolean

  true if all non-Links were added to this Group; false if some Parts or Nodes were not able to be added.

### `Virtual` canAddMembers

- canAddMembers(coll: Iterable<Part>): boolean

- See if the given collection of Parts contains non-Links all for which CommandHandler.isValidMember returns true.

  The CommandHandler predicate will use CommandHandler.memberValidation and memberValidation, if either or both are defined.

  This does not check Diagram.isReadOnly or Model.isReadOnly, but commands and tools should check those properties.

  #### Parameters

  - ##### coll: Iterable<Part>

  #### Returns boolean

  true.

### `Virtual` canUngroup

- canUngroup(): boolean

- This predicate returns true if ungroupable is true, if the layer's Layer.allowUngroup is true, and if the diagram's Diagram.allowUngroup is true.

  This does not check Diagram.isReadOnly or Model.isReadOnly, but commands and tools should check those properties.

  #### Returns boolean

  true if the user may ungroup this object.

### collapseSubGraph

- collapseSubGraph(): void

- Hide each of the member nodes and links of this group, and recursively collapse any member groups. This changes the value of Part.isVisible of the whole subgraph and the parts owned by those member nodes and links. However, this group's visibility is unchanged.

  This sets isSubGraphExpanded to false on this group and on all of the nested Groups. For those nested Groups that were expanded, wasSubGraphExpanded is set to true.

  This method does not perform a transaction or start any animation.

  To collapse trees made of Nodes and Links, use Node.collapseTree.

  #### Returns void

### expandSubGraph

- expandSubGraph(): void

- Show each member node and link, and perhaps recursively expand nested subgraphs. This may change the value of Part.isVisible of the whole subgraph and the parts owned by those member nodes and links. However, this group's visibility is unchanged.

  This sets isSubGraphExpanded to true on this group and on all of the nested Groups. This will expand a nested group only if its wasSubGraphExpanded property was true.

  This method does not perform a transaction or start any animation.

  To expand trees made of Nodes and Links, use Node.expandTree.

  #### Returns void

### findExternalLinksConnected

- findExternalLinksConnected(): Iterator<Link>

- Returns an iterator over all of the Links that connect with this group or any node contained by this group, in either direction, but that are not internal to this group.

  Links that are contained by this group (even in nested groups) are not included in the result collection.

  #### Returns Iterator<Link>

  `see`

  Node.findLinksConnected

### findExternalNodesConnected

- findExternalNodesConnected(): Iterator<Node>

- Returns an iterator over all of the Nodes that are connected with this group or any node contained by this group, by a link in either direction, but that are not internal to this group.

  Nodes that are contained by this group (even in nested groups) are not included in the result collection. However this group itself might be in the results if there is a reflexive link connected to this group.

  #### Returns Iterator<Node>

  `see`

  Node.findNodesConnected

### findSubGraphParts

- findSubGraphParts(): Set<Part>

- Return a collection of Parts that are all of the nodes and links that are members of this group, including inside nested groups and label nodes, but excluding this group itself.

  For member nodes that are Groups, this will include its members recursively.

  If you want only the immediate members of this group, use the memberParts property.

  If you want to find the collection of Nodes and Links that are in the subtree of a given Node, use Node.findTreeParts.

  #### Returns Set<Part>

### `Override` move

- move(newpos: Point, useLocation?: boolean): void

- Move this Group and all of its member parts, recursively.

  This method does not perform a transaction or start any animation.

  #### Parameters

  - ##### newpos: Point

    a new Point in document coordinates.

  - ##### `Optional` useLocation: boolean

    true if you want to set the location instead of the position. False by default.

  #### Returns void

Copyright © 1998-2024 by Northwoods Software Corporation.