JDiagram allows attaching a node to another diagram element, establishing a subordinate - master relationship between the two items. The easiest way to attach nodes is to call the attachTo method. When a master element is moved or resized, any subordinated node follows it, so that the initial distance between the two items stays constant. This happens both when a user moves the master item around, and when the item position is changed using a method.

Possible Uses

• Attach a transparent shape node to another item and set its text by calling the setText method, so that the shape node acts as an additional label assigned to the main item (to make a shape node transparent, call its setTransparent method).
• Attach a shape node to another item and set the node's image by calling its setImage method, so that it acts as an additional icon displayed inside or near the main item.
• Attach a shape node or a table to another item and handle the nodeClicked or cellClicked event to perform some action on the main item. This makes the subordinated node act as a button or another type of UI element attached to the main item.
• In all previous cases, the attached nodes can be locked by a call to their setLocked method in order to use them only as a decorations embellishing the main item. That prevents users from selecting, modifying or drawing links to the subordinates.
• Attach child elements in a tree branch to the branch root, so that when a user moves a tree node, the node's children moves simultaneously with it. Modifying an item in such hierarchical group makes the modification propagate through all dependant subordinated items.

Hierarchical Grouping

An unit of attached items is represented by an instance of the Group class. To create a group, call the createGroup method passing the master object as argument, and use the Group methods to attach items. The attachTo method of nodes is a shortcut to creating a group and attaching an item to it. Every member of a group can be the master object of another group, that is, an item can be subordinate in one group and meanwhile be another group's master. JDiagram doesn't impose any limits to the depth and width of group hierarchies built that way. However, it is not possible to put an item as a subordinate in more than one groups because the hierarchy relations would become ambiguous.

Unions

It is possible to create such groups, where modifying any item in the hierarchy causes updating of all other items. This can be done by putting the items in circular chain of dependencies - that is, item1 is attached to item2, item2 to item3 … itemN to item1. If any of these items is modified, the change will propagate through the chain until it reaches its originator.

Attaching Items to a Group

Links cannot be attached to groups but can be master items of groups. If a group's master item is a link, nodes can be attached to the control points or segments of the link. See the attachToLinkPoint and attachToLinkSegment methods for details. If the master item is a node, other nodes can be attached to any of its corners, or to an area specified as percent of master-node's bounding rectangle. Check attachToCorner and attachProportional for details. A shortcut to creating Group instance and calling the appropriate attachTo method of the DiagramNode class.

Accessing Group Items

The master item of a group can be accessed through its getMainItem method and the subordinate items are returned by the getAttachedNodes method. To get the groups in which an item participates, use its getMasterGroup and getSubordinateGroup methods.

Destroying Groups

If a user deletes the master item of a group, the group is destroyed automatically. If getAutoDeleteItems returns true, subordinated items in the group are deleted too. If getAutoDeleteItems returns false, subordinated items are just detached from their master and remain intact. Groups can be destroyed programmatically using the destroyGroup method.