Most likely an application would use JDiagram to enable users to interactively create diagrams, flowcharts and other kinds of presentation documents. A user composes or edits a diagram by drawing its elements on the JDiagram canvas area. With the help of a mouse or another pointing device users draw shapes, tables and links, possibly connecting them in complex hierarchies, graphs, trees or other structures they might need.

Creating New Items

New items can be created by drawing them with the mouse. While a user drags the mouse, the view of the control is updated to show what the new item would look like at the pointer location. If the operation cannot be completed at the current mouse position, the cursor changes to a crossed out circle. When the user releases the button, the item is created. The control does not let users create very tiny nodes which would be hard to select and modify. By default, links can be drawn only between nodes, unless the AllowUnconnectedLinks attribute is enabled. Users can cancel item creation by pressing the right mouse button while drawing.

Modifying Items

A user modifies an item by dragging its adjustment handles. The setModificationStart method specifies when these handles appear. The first option, AutoHandles, makes the handles appear when the mouse hovers over an item; modification of the item can start immediately by pointing it and dragging a handle. The second option is SelectedOnly: in order to be modified, an item should first be selected. Adjustment handles appear around the item to indicate that now it can be moved or resized. The number and functionality of the handles depend on the item type and the value specified through the setHandlesStyle method.

Modifying a Node

Usually nodes have nine adjustment handles. The one at the center can be used to move the node. When dragged, each corner handle resizes the node by moving the two edges adjacent to the corresponding corner. The edge handles placed at the center of each side can be used to resize a node either horizontally or vertically. Shape nodes can be rotated using an additional round handle drawn above them. Each handle can be enabled or disabled by setting or clearing the respective bit through the setEnabledHandles method.

Modifying a Link

Variety and behavior of link adjustment handles depend on the link's Style and SegmentCount. Control-points stay at both ends of each segment that constitutes a link. JDiagram offers three link styles. The following sections discuss how to modify links of each style.

• The first style called Polyline defines links, which consist of a series of straight segments, drawn between control-points. There are no restrictions as to the number of segments. Dragging a control-point modifies each segment adjacent to the point. If the setAllowSplitLinks method is called, users are allowed to insert new control points or to remove existing ones. Inserting a control point is done by pressing the left mouse button over a segment and dragging. The new point appears at the mouse location and splits the pointed segment in two.
• If link's style is set to Bezier, each segment has 4 manipulation handles that define a curve. Each curve goes through the end-points, which are shaped as circles. Bend of the curve is defined by the middle two points shaped as rectangles. If a user drags an end-point modification handle, the adjacent control points will be moved with same translation vector as that of the end-point. If a bend control point is dragged, the symmetric control point of the neighboring curve is also moved to ensure the two stay on the same line with the end-point and on the same distance from it.
• Cascading links consist of straight horizontal and vertical segments, each one orthogonal to its neighbors. If a control-point is dragged, the segments adjacent to it are moved and resized preserving their orthogonal orientation to each other. If the setAllowSplitLinks method is called, users are allowed to insert new control points to Cascading links or remove existing ones. The orientation of the link segments can be changed if LinkCascadeOrientation is set to Auto.

Modifying a Table

By default, table modification handles are drawn as dotted lines over its borders. To move a table, drag its caption bar. To resize a table, drag any of its borders or corners.

Selecting Items

Multiple items are selected by dragging while CTRL key is down. Selection can also be toggled with CTRL + clicking an item. A rectangle appears around selected items, allowing a user to move all of them at once.

Scrolling and Panning

The DiagramView can be scrolled if its placed inside a JScrollPane. Users scroll the view by dragging the scrollpane's scrollbars, which appear when the diagram area is larger than the view. The user could also pan the diagram view by pressing the left mouse button and dragging while the ALT key is down.

Interpreting Users Actions

Mouse operations can be interpreted in different ways depending on the value of the Behavior property. It defines whether for example dragging the mouse creates a node or selects existing items. Check the property description for more information on the built-in input modes.

You can also create a custom mouse input controller by deriving from the BehaviorBase class and calling the setCustomBehavior method of DiagramView. A custom controller could implement only the higher-level startDraw method to specify what kind of operation should start when the user begins to drag the mouse, or the createNode method to create an instance of a custom node class. Alternatively, override the lower-level pointerDown, pointerMove and pointerUp methods to completely overhaul user interaction. A custom BehaviorBase-derived class is demonstrated in the Fishbone sample project.