Controlling User Interaction

There are several ways to control user actions on the diagram as a whole, or on individual items in the diagram.

Drawing Modes

The behavior property of DiagramView provides several predefined sets of rules specifying how to interpret user input through pointing device. The default behavior is LinkShapes, where drawing with mouse or touch from an unoccupied point of the document is processed as a ShapeNode creation request, and drawing from a node creates a DiagramLink. Additional members of the Behavior enumeration provide modes for drawing different node types, and ones that allow only limited interactions, such as SelectOnly or Modify.

In-place Text Editing

The text of nodes and links can be edited in-place by double-clicking the respective items. To enable this feature, set the allowInplaceEdit property to true. Depending on the type of item, the control raises either the nodeTextEdited, cellTextEdited or linkTextEdited event when its text has been edited. In-place editing mode is exited when users click outside the text entry control. Pressing ENTER or ESC exits inplace-edit mode if respectively inplaceEditAcceptOnEnter and inplaceEditCancelOnEsc are enabled.

By default, the control creates a textarea DOM element over an item to allow editing the item's text. If you prefer using a different type of element as in-place editor, handle the createEditControl event and set the control property of the provided InplaceEditEventArgs object.

Validation Events

While the user draws new nodes or links, the control raises the nodeCreating or linkCreating events after each change of the mouse position. By setting the cancel property of the event object, you can prevent the operation from being completed at the current position but let the user continue drawing. Calling the cancelDrag method immediately stops the operation. The nodeModifying and linkModifying events provide the same functionality during modification of existing objects. Finally, if the user tries to delete an item, you can handle the nodeDeleting or linkDeleting event to prevent this.

Interaction Properties

• allowSelfLoops property of Diagram specifies whether users can draw reflexive / self-loop links.
• allowUnconnectedLinks property specifies whether users can create links without connecting them to nodes (e.g. for simple line or curve graphics in a drawing).
• delKeyAction specifies how the DiagramView handles the Delete key.
• modifierKeyActions allows changing the function of modifier keys.
• leftButtonActions, middleButtonActions and rightButtonActions allow mapping interaction types to mouse buttons.
• mouseWheelAction allows changing the function of the mouse wheel.
• allowIncomingLinks and allowOutgoingLinks properties of DiagramNode specify if a node accepts respective types of links.
• setting the locked property of a DiagramItem prevents users from interacting with it altogether.

Multi-touch Support

The control handles DOM Pointer events to implement multi-touch interactions, such as zooming, node rotation or simultaneous drawing of multiple diagram items:

• If multiTouchZoom property is enabled (default), the view can be zoomed or panned using two-touch pinch / flick gestures.
• If multiTouchModify property is enabled (default), diagram nodes can be moved, scaled and rotated using two-touch pinch / flick gestures.
• If multiTouchZoom property is disabled, each touch draws diagram items corresponding to current behavior.
• If multiTouchModify property is disabled, each touch started from a node draws a diagram link.

Latter modes can be used for collaborative whiteboarding / classroom scenarios.

Built-in multi-touch can be disabled altogether by setting enableMultiTouch to false, e.g. if you need to handle touch events yourself or through a third-party gesture library. If disabled, the control will revert to its mouse event handling code from previous versions. It will also no longer be able to capture mouse input during drag operations (to detect mouse pointer leaving the view), which is handled through DOM Pointers API.

User-interaction controllers

All kinds of user interaction are carried out by controller objects. Built-in controllers include CreateNodeController, CreateLinkController, ModifyNodeController, ModifyLinkController, PanController. You can also create custom controllers by deriving and overriding the methods of SinglePointerController:

JavaScript

SinglePointerController.prototype =
{
    start: function (position) {},
    move: function (position) {},
    validate: function (position) {},
    commit: function (position) {},
    cancel: function (position) {},
    drawInteraction: function (context) {}
}

The controller instance used by the diagram when interaction starts is returned by createController method of BehaviorBase -derived classes. You can replace the method of standard behavior classes with a custom function to return a different controller, or inherit a new class from BehaviorBase that implements it and assign it to the currentBehavior property of DiagramView.