Tools

Tools handle all of the input events. There are many kinds of predefined Tool classes that implement all of the common operations that users do.

For flexibility and simplicity, all input events are canonicalized as InputEvents and redirected by the diagram to go to the Diagram.currentTool. By default, the Diagram.currentTool is an instance of ToolManager held as the Diagram.toolManager. The ToolManager implements support for all mode-less tools. The ToolManager is responsible for finding another tool that is ready to run and then making it the new current tool. This causes the new tool to process all of the input events (mouse, keyboard, and touch) until the tool decides that it is finished, at which time the diagram's current tool reverts back to the Diagram.defaultTool, which is normally the ToolManager, again.

Although the terminology includes the word "mouse", often that refers to both mouse events and touch events.

See samples that make use of Tools in the samples index.

Predefined Tools

Each Diagram has an instance of most of the tool classes, all managed by the diagram's ToolManager. If you want to change the interactive behavior, in many common cases you may be able to do so by setting properties on the Diagram, on your Parts, or on individual GraphObjects. But more generally you may need to modify one or more of the tools, which are accessible as properties of the Diagram.toolManager.

Some tools want to run when a mouse-down occurs. These tools include:

Tool	Class	Purpose
ToolManager.actionTool	ActionTool	for allowing "buttons" and other GraphObjects to grab events from the regular tools
ToolManager.relinkingTool	RelinkingTool	for reconnecting an existing Link
ToolManager.linkReshapingTool	LinkReshapingTool	for changing the route of a Link
ToolManager.resizingTool	ResizingTool	for changing the GraphObject.desiredSize of a Part or an object within a Part
ToolManager.rotatingTool	RotatingTool	for changing the GraphObject.angle of a Part or an object within a Part

Some tools want to run when a mouse-move occurs after a mouse-down. These tools include:

Tool	Class	Purpose
ToolManager.linkingTool	LinkingTool	for drawing a new Link
ToolManager.draggingTool	DraggingTool	for moving or copying selected Parts
ToolManager.dragSelectingTool	DragSelectingTool	for rubber-band selection of some Parts within a rectangular area
ToolManager.panningTool	PanningTool	for panning/scrolling the diagram

Some tools only want to run upon a mouse-up event after a mouse-down. These tools include:

Tool	Class	Purpose
ToolManager.contextMenuTool	ContextMenuTool	for showing a context menu for a GraphObject
ToolManager.textEditingTool	TextEditingTool	for in-place editing of TextBlocks in selected Parts
ToolManager.clickCreatingTool	ClickCreatingTool	for inserting a new Part when the user clicked
ToolManager.clickSelectingTool	ClickSelectingTool	for selecting or de-selecting a Part

To change the behavior of a tool, you may be able to set properties on the tool, on the Diagram, on a particular Part, or on a particular GraphObject.

Tool	Setting	Effect
DragSelectingTool	`diagram.toolManager.dragSelectingTool.isEnabled = false;`	Disable the rubber-band selection tool.
ClickSelectingTool	Part.selectionAdornmentTemplate	Change the appearance of a selected Part (actually its selection Adornment). (See Selection for more discussion.)
LinkingTool	GraphObject.fromLinkable, GraphObject.toLinkable	Enable users to draw new links interactively by setting these on the port objects of your nodes.
DraggingTool	Part.movable	Disable the movement of a Part, including Nodes and Groups, by setting this to false.
DraggingTool	Part.minLocation, Part.maxLocation, Part.dragComputation	Limit the movement of a Part. For more general limitations, set Part.dragComputation to a function that computes the desired new location.
ResizingTool	Diagram.allowResize	Disable resizing any part by setting this to false.
ToolManager	—	Tooltips are discussed in ToolTips.
ContextMenuTool	—	Context menus are discussed in Context Menus.

More detail is available in the section about Permissions.

Some commonly set properties include:

Tool	Properties	Effect
ClickCreatingTool	ClickCreatingTool.archetypeNodeData	Enable inserting parts via double-clicking by setting this to a node data object.
DragSelectingTool	DragSelectingTool.isPartialInclusion	Control what parts become selected.
LinkingTool	LinkingTool.archetypeLinkData	Customize the link data that is copied when a new link is drawn.
ResizingTool	ResizingTool.cellSize, ResizingTool.maxSize, ResizingTool.minSize	Limit how parts are resized.
RotatingTool	RotatingTool.snapAngleEpsilon, RotatingTool.snapAngleMultiple	Limit how parts are rotated.

Remember that all of the individual tools are available via the Diagram.toolManager. For example, to enable the ClickCreatingTool:

You can also set tool properties when using the constructor to define your Diagram:

At this time the syntax for setting properties on predefined subobjects only works for the Diagram constructor.

The Tool lifecycle

While each prebuilt tool in GoJS is used for a different purpose, all Tools are guaranteed to share some functions and properties. All tools share a general "lifecycle" -- that is, the order in which these common functions are called. One can think of this cycle as "starting" when the ToolManager is alerted of some input event and begins searching through the pertinent list of tools (i.e., if the mouse-down event is registered, ToolManager starts searching its ToolManager.mouseDownTools list). Below is a diagram representing the general lifecycle of a tool.

For more information on how these specific functions work, see the Tool documentation.

Tools and Adornments

Adornments are used for more than indicating that a Part is selected. Each Tool that is in the ToolManager.mouseDownTools list (in other words, any mode-less tool that is started with a mouse-down or finger-down event) gets the opportunity to add its own Adornments for its own purposes when a Part is selected.

ResizingTool

When a Part is resizable, the ResizingTool adds an Adornment containing eight resize handles, four at the corners and four at the middles of the sides.

If you want to let the user resize the whole node, just set Part.resizable to true. In this case resizing will set the Node's GraphObject.desiredSize.

If you want the user to resize a particular object within the node, you need to name that object and assign Part.resizeObjectName. Resizing will set the Part.resizeObject's GraphObject.desiredSize, in this case the Shape's desiredSize.

You can limit the minimum and maximum size for the resized object by setting GraphObject.maxSize and GraphObject.minSize. Note that these GraphObject properties are set on the Part.resizeObject, not on the Part itself.

You can also cause resizing to be multiples of a given size by setting Part.resizeCellSize.

When an object is resizable, it is commonplace to try to remember the new size by updating the model data, so that it can be saved and loaded later. This can be accomplished with a TwoWay Binding on the GraphObject.desiredSize property. But note that the binding needs to be on the actual GraphObject that is resized, not on the whole Node. In this case, because the Part.resizeObjectName is referring to a Shape, that means the binding needs to be on the Shape.

You can customize all eight standard resize handles by setting ResizingTool.archetypeHandle. For example, to change all of the handles to be slightly larger yellow circles:

Note that the ResizingTool will automatically set each resize handle's GraphObject.cursor appropriately. Note also that because Part.selectionAdorned is false, there is no blue rectangle default selection adornment.

You can customize the resize handles by setting Part.resizeAdornmentTemplate. For example, to allow the user to only change the width of a Shape in a Node, the Adornment should have only two resize handles: one at the left and one at the right. The Adornment is implemented as a Spot Panel that surrounds a Placeholder, representing the adorned Shape, with two rectangular blue Shapes, each representing a handle. There is also a TextBlock placed above the adorned shape showing the shape's current width.

There are examples custom resizing tools defined in the samples and extensions directories: Resize Multiple Tool, Lane Resizing Tool (in Swim Lanes), and Lane Resizing Tool (in Swim Lanes Vertical).

RotatingTool

When a Part is rotatable, the RotatingTool adds an Adornment containing one rotate handle a short distance from the object at the object's angle. Since the default GraphObject.angle is zero, the rotate handle typically starts to the right of the object.

If you want to let the user rotate the whole node, just set Part.rotatable to true. Rotating will set the Node's GraphObject.angle.

If you want the user to rotate a particular object within the node, you need to name that object and assign Part.rotateObjectName. Rotating will set the Part.rotateObject's GraphObject.angle, in this case the Shape's angle.

When an object is rotatable, it is commonplace to try to remember the new angle by updating the model data, so that it can be saved and loaded later. This can be accomplished with a TwoWay Binding on the GraphObject.angle property. But note that the binding needs to be on the actual GraphObject that is rotated, not on the whole Node. In this case, because the Part.rotateObjectName is referring to a Shape, that means the binding needs to be on the Shape.

You can customize the rotate handle by setting Part.rotateAdornmentTemplate. Another common customization is to position the rotate handle above the object when it is not rotated, i.e. when its GraphObject.angle is zero. This is accomplished by setting RotatingTool.handleAngle to 270.

There are example custom rotating tools defined in the samples and extensions directories: Rotate Multiple Tool and Horizontal Text Rotating Tool (in Seating Chart).

RelinkingTool

When a Link is Link.relinkableFrom and/or Link.relinkableTo, the RelinkingTool adds one or two Adornments, a diamond at each relinkable end of a selected link. The user can drag a relinking handle to reconnect that end of the link to another port.

The RelinkingTool will automatically update the relationships between the nodes/ports, both in the diagram and in the model. No Bindings are needed for such model updates.

The relinking handles can be customized by setting RelinkingTool.fromHandleArchetype and RelinkingTool.toHandleArchetype. At the current time they cannot be customized by setting a property on the Link.

You can limit which pairs of ports between which the user may draw new links or reconnect existing links. This topic is covered by Link Validation.

LinkReshapingTool

When a Link is Part.reshapable, the LinkReshapingTool adds an Adornment with several reshape handles at the interior points of a selected link's route. When the user drags a reshape handle, the route of the Link, held by Link.points, is modified.

When a link is reshapable, it is commonplace to try to remember the new route by updating the link data in the GraphLinksModel, so that it can be saved and loaded later. This can be accomplished with a TwoWay Binding on the Link.points property. If one also uses the property name "points" on the link data, Model.toJson will automatically convert the List of Points into an Array of numbers and vice-versa.

The reshape handles are small blue squares. The reshape handles can be customized by setting LinkReshapingTool.handleArchetype. At the current time they cannot be customized by setting a property on the Link.

By setting Link.resegmentable to true, users can add or remove segments from links. The resegmenting handles are even smaller blue diamonds at the middle of each segment. When the user drags a resegmenting handle, a new segment is inserted into the link's route. For orthogonal links, two new segments are introduced in order to maintain orthogonality. When the user reshapes the link so that adjacent segments are co-linear (or nearly so), the segment(s) are removed from the route.

The resegmenting handles can be customized by setting LinkReshapingTool.midHandleArchetype. At the current time they cannot be customized by setting a property on the Link. Also at the current time resegmenting is not supported on Bezier-curved links.

If you want your users to be able to reshape Shape geometries that are not Link paths, there is the Geometry Reshaping Tool used by the Polygon Drawing and Freehand Drawing samples in the extensions directory. It is defined in a separate JS file that you can load into your app.

Tools and Tool Parts

Some tools make use of special Parts that they add to the "Tool" Layer as feedback during the tool's operation.

DragSelectingTool

The DragSelectingTool uses the DragSelectingTool.box to show the area in which it will select Parts. Normally this is a simple magenta rectangular shape, which you can customize. For example here is a drag-selecting box that is in the shape of a blue-outlined cloud.

Note that the DragSelectingTool expects that the object in the "box" to be resized is named "SHAPE". The object should be rectangular too, or else the user might be misled by the area in which parts will be selected. Finally note also that the box is not an Adornment because it does not "adorn" any Part. It is just an unbound Part that is used temporarily by the DragSelectingTool.

There are examples of in-the-background-dragging tools defined in the extensions directory: Realtime Drag Selecting Tool, Drag Creating Tool, and Drag Zooming Tool. Each is defined in a separate JS file that you can load into your app.

LinkingTool and RelinkingTool

The linking tools, LinkingTool and RelinkingTool, inherit from a base class, LinkingBaseTool, that uses several Parts: a temporary Link and temporary "to" and "from" Nodes.

To customize the appearance and behavior of the temporary Link that is shown during a linking operation, you need to modify or replace the LinkingBaseTool.temporaryLink. Same goes with the LinkingBaseTool.temporaryFromNode and LinkingBaseTool.temporaryToNode. You may also want to set the corresponding temporary port properties as well. The default temporary link is a blue line with a standard arrowhead. The originating port and the potential target port are shown by the LinkingBaseTool.temporaryFromNode and LinkingBaseTool.temporaryToNode. The default temporary ports are magenta rectangles.

Try drawing a link from one node to the other. You will notice that the nodes (actually the ports) are highlighted by the temporary nodes in chartreuse and cyan. The temporary link is a dashed red line without an arrowhead.

If your app also supports relinking you will probably want to do the same customizations on the RelinkingTool.

There are examples of linking tools defined in the samples and extensions directories: Polyline Linking Tool, Messaging Tool (in Sequence Diagram), and Custom Linking Tool (in Grafcet Diagram)

Custom Tools

The GoJS samples and extensions demonstrate a number of custom tools, including: