Class Group

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.