Most likely an application would use DroidDiagram 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 DroidDiagram canvas area. By drawing on the touch screen, users can create shapes, tables and links, possibly connecting them in complex hierarchies, graphs, trees or other visualization structures they might need.

Creating New Items

New nodes can be created by drawing on the touch screen, starting from unoccupied area of the diagram. While the user draws, the view of the control is updated to show what the new item would look like at the current finger location. When the user lifts their finger, 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 touching the screen with a second finger.

Modifying Items

A user modifies an item by dragging its adjustment handles. 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. DroidDiagram offers three link Shape 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 touching any point of a segment and dragging. The new control point appears at the touch 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, TableNode modification handles are drawn as dotted lines over the node borders. To move a table, drag its caption area. To resize a table, drag any of its sides or corners.

Selecting Items

A single item can be selected by a short press, which removes all previous items from the selection. A long press toggles the item selection state, letting you add multiple items to the selection. Multiple items can also be selected by drawing a selection frame around them, when Behavior is set to Modify. There is a rectangle drawn over multiple selected items, allowing the user to move all of them at once.

Context menu

A long press over a diagram item displays a radial menu that lets users delete the item, edit its text or toggle its selection state. Handle the contextMenuOpening event to customize the menu by adding new items or removing standard ones. You can add a new item by calling the addMenuItem method or by adding a new RadialMenuItem instance to the Items list. A long press in older versions of the library used to toggle selection, so for compatibility the selection menu item is considered a default one and its action is executed unless the user explicitly chooses another menu item. You can change this default by calling the setDefaultItem method.

If there is no diagram item located at touch position, the control raises contextMenuOpening and displays a menu only if the event handler adds any custom items.

Scrolling and Panning

If the diagram is larger than the DiagramView, a user can scroll the view by dragging with two fingers. It is also possible to scroll it with a single finger, if Behavior is set to Pan.

Interpreting Users Actions

User interaction can be interpreted in different ways depending on the value of the Behavior property. It defines whether for example drawing with a finger 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 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 draw, 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.