Interacting with diagrams

Built-in GoJS interactivity

GoJS implements a number of common editing operations such as manipulating parts -- moving, adding, copying, cutting, and deleting Nodes and Links. These editing abilities are accessible via mouse or touch and keyboard by default, and can also be invoked programmatically in JavaScript.

The following Diagram defines a node template and has four nodes in its model:

Out of the box, several interactions are available:

Click a node to select it. Press and drag on a node to move it around. Or press and drag in the diagram background to pan the entire Diagram.
Common keyboard shortcuts such as Ctrl-C, Ctrl-V, Ctrl-X will copy, paste, and cut diagram parts, respectively. (Use the Command modifier on a Mac.) Note that copies will copy the location of the Node as well, unless a layout or the paste command moves the new node.
Press-hold-and-drag in the background of the diagram allows you to create a selection box for selecting multiple nodes. Ctrl-clicking on nodes allows you to toggle their selection. Shift-clicking on nodes makes sure they are selected.
Since the Diagram's undoManager was enabled, Ctrl-Z and Ctrl-Y (or Ctrl-Shift-Z) will undo and redo operations. Panning (scrolling), zooming, and selection are not considered undoable operations.

By setting a few properties you can expose more interaction to a user, including manipulating groups:

ClickCreatingTool.archetypeNodeData allows a double-click in the background to create a new node with a copy of the specified data.
CommandHandler.archetypeGroupData allows Ctrl-G to group a selection of nodes, with the group getting a copy of the specified data in the model.
Group.ungroupable allows Ctrl-Shift-G to ungroup a selected group.
ToolManager.mouseWheelBehavior allows the mouse wheel to zoom instead of scroll by default. You can toggle this property by clicking on the mouse-wheel. On touch devices, pinch-zooming is enabled by default.
TextBlock.editable in the TextBlock definition allows the text to be edited in place by the user. Select a node and then click on the text, or press F2, to begin text editing. Click anywhere else on the diagram or press Tab to finish editing text.

These interactions (and more!) are all present in the Basic sample. Be sure to also see the learn page on commands.

You can disable portions of Diagram interactivity with several properties, depending on what you want to allow users to do. See the learn page on permissions for more explanation.

Focus and keyboard control of Tools

You have always been able to manipulate diagrams using the mouse without using the keyboard, especially when making use of the default context menu, which has always been needed on touch devices. As of version 3.1 if you have a keyboard you no longer need to use the mouse to manipulate almost any diagram. This keyboard control mode, when enabled, is available as long as the diagram has keyboard focus. You can always Tab out of the diagram.

Because the GraphObjects within a Diagram are not HTML elements, there is a separate GoJS focus object that is a GraphObject. The arrow keys, Enter, and Escape can change which GraphObject has GoJS focus.

Additionally there is a virtual pointer acting as if it were the mouse, visible when the Shift key is held down. Control the virtual pointer using Shift-arrow keys, Shift Numpad0-9 keys, Shift-Enter, and a few other keys modified by Shift.

Version 3.1 also includes built-in support for screen readers. However, we recommend that you customize the behavior to provide the best possible experience for your users.

(On a Mac, use the Command modifier insead of the Control modifier.)

Type Ctrl-Alt-Enter to enable "keyboard control mode", if it hasn't already been turned on programmatically. That key chord will toggle this mode on and off.
GoJS focus is shown by a double-colored dashed box around the GraphObject.
Use the arrow keys to move focus around to other Nodes or other kinds of Parts. Use Ctrl arrow keys to follow a Link connected with a focused Node.
Type Space to select a Part (a Node or a Link), Shift-Space to add a Part to the selection, and Ctrl-Space to toggle selection of a Part.
Using Enter on a focused Node, if there are any GraphObjects within the Node that can be focused, will change focus to be on one such object, and arrow keys will keep focus within the Node.
When focus is inside a Node, Enter will activate the focused object: click a button, start editing a TextBlock, or show a tooltip. Space will only show a tooltip, if one is available.
When focus is inside a Node, Escape will change focus to be on the Node again.
When focus is on a Group, Enter will first focus on focusable GraphObjects, if any, just as for regular Nodes, and then Escape will focus on the Group's member Nodes, if any, and finally Escape will focus on the Group again.
Use the ContextMenu key to show any context menu for the object with GoJS focus.
All other keyboard commands work normally, such as Delete of the selection, or Ctrl-Z to undo.
Hold down a Shift key to show a magenta cross-hair virtual pointer that acts like the mouse. You can let go of the Shift key at any time without losing any state.
Shift arrow keys move the virtual pointer around. With the Ctrl-Shift modifiers they only move a pixel at a time. You can also use Shift-Numpad1 through Shift-Numpad9 (except Shift-Numpad5) to move the virtual pointer around. Unlike the arrow keys, you will be able to move the virtual pointer on the diagonals.
Shift-Enter or Shift-Numpad5 toggles the mouse button down or up.
Tab works normally to change keyboard focus to the next HTML element after the Diagram. If the diagram is showing scrollbars, Tab will focus on the HTML element holding the scrollbars, allowing for the arrow keys to scroll normally.
Note that when using the Windows Narrator screen reader you will need to stop Scan Mode via the CapsLock-Space command.

See the learn page on accessibility for demos and more explanation.

Tooltips

GoJS provides a mechanism for you to define tooltips for any object or for the Diagram itself. In the example below, two tooltips are defined, one on the Node template and one on the Diagram.

Hover over a node to show the node's tooltip for five seconds. Hover anywhere in the viewport not over a node to see the tooltip for the diagram.

The basic sample contains more complex tooltip examples. See the learn page on tooltips for more discussion.

Context menus

GoJS provides a mechanism for you to define context menus for any object or for the Diagram itself. In the example below, two context menus are defined, one on the Node template (with one button) and one on the Diagram (with two buttons).

If you right-click (or long-tap on a touch device) on a Node or the Diagram, you will see the GoJS context menu appear with the defined options.

The basic sample contains more complex context menu examples. See the learn page on context menus for more discussion.

Link interactions

GoJS lets users draw new Links by dragging out from a port on a Node to another port on a Node. Users can reconnect existing links by selecting one and dragging one of its handles. To enable these behaviors, some properties need to be set:

In the above example:

The Node's Shape has its portId set to make it the port instead of the entire Node. Then several ...Linkable... properties are set, allowing each node to link to itself and to others. Depending on the functionality you want to provide to your users, you may not want to set all of those properties on your ports in your node templates.
To draw a new link to another node, drag from the port (the edge of the Shape that is not behind the TextBlock) to any node, including itself.
In the link template, relinkable... properties are set, so that when the link is selected, it shows handles that can be dragged in order to reconnect the link with a different node.

GoJS allows linking and re-linking to abide by custom criteria that controls whether a link connection would be valid. You can read about this in the learn page on validation.

GoJS links have many interesting properties that are covered in depth in the learn page on Links and on the following pages.

You may want to read more tutorials, such as the Quick Start and the GraphObject Manipulation Tutorial.

If you want to explore by example, have a look at the samples to get a feel for what's possible with GoJS.