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:

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

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

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.

More detail is available in the section about Permissions.

Some commonly set properties include:

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

  myDiagram.toolManager.clickCreatingTool.archetypeNodeData =
    { key: "Node", text: "some description", color: "green" };

You can also set tool properties when using GraphObject.make to define your Diagram: 

  var diagram =
    $(go.Diagram, "myDiagramDiv",
      {
        initialContentAlignment: go.Spot.Center,
        allowDrop: true,
        "grid.visible": true,
        "grid.gridCellSize": new go.Size(30, 20),
        "clickCreatingTool.archetypeNodeData":  // a node data JavaScript object
          { key: "Node", text: "some description", color: "green" },
        "dragSelectingTool.box":  // an unbound Part
          $(go.Part, { layerName: "Tool" },
            $(go.Shape, { name: "SHAPE", fill: null, stroke: "blue", strokeWidth: 3 }) ),
        "draggingTool.isGridSnapEnabled": true,
        "linkReshapingTool.handleArchetype":  // a GraphObject that is copied for each handle
          $(go.Shape, { width: 10, height: 10, fill: "yellow" }),
        "resizingTool.isGridSnapEnabled": true,
        "rotatingTool.snapAngleMultiple": 90,
        "rotatingTool.snapAngleEpsilon": 45
      }
    );

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

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Auto",
      { resizable: true },
      $(go.Shape, "RoundedRectangle", { fill: "orange" }),
      $(go.TextBlock, "Hello!", { margin: 5 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",  // resize the Shape, not the Node
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30,
          // limit size by setting or binding maxSize and/or minSize
          maxSize: new go.Size(100, 40), minSize: new go.Size(20, 20) }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",
        resizeCellSize: new go.Size(10, 10),  // new size will be multiples of resizeCellSize
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30,
          maxSize: new go.Size(100, 40), minSize: new go.Size(20, 20) }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 },
        // TwoWay Binding of the desiredSize
        new go.Binding("desiredSize", "size", go.Size.parse).makeTwoWay(go.Size.stringify)),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",
        resizeAdornmentTemplate:  // specify what resize handles there are and how they look
          $(go.Adornment, "Spot",
            $(go.Placeholder),  // takes size and position of adorned object
            $(go.Shape, "Circle",  // left resize handle
              { alignment: go.Spot.Left, cursor: "col-resize",
                desiredSize: new go.Size(9, 9), fill: "lightblue", stroke: "dodgerblue" }),
            $(go.Shape, "Circle",  // right resize handle
              { alignment: go.Spot.Right, cursor: "col-resize",
                desiredSize: new go.Size(9, 9), fill: "lightblue", stroke: "dodgerblue" }),
            $(go.TextBlock, // show the width as text
              { alignment: go.Spot.Top, alignmentFocus: new go.Spot(0.5, 1, 0, -2),
                stroke: "dodgerblue" },
              new go.Binding("text", "adornedObject",
                             function(shp) { return shp.naturalBounds.width.toFixed(0); })
                  .ofObject())
          ),
        selectionAdorned: false },  // don't show selection Adornment, a rectangle
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30,
          maxSize: new go.Size(100, 40), minSize: new go.Size(20, 20) }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

Note also that because Part.selectionAdorned is false, there is no blue rectangle default selection adornment.

There are examples custom resizing tools defined in the samples and extensions directories: Resize Multiple Tool (in Floor Plan Editor), 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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Auto",
      { rotatable: true, locationSpot: go.Spot.Center },
      $(go.Shape, "RoundedRectangle", { fill: "orange" }),
      $(go.TextBlock, "Hello!", { margin: 5 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { rotatable: true, rotateObjectName: "SHAPE",  // rotate the Shape, not the Node
        locationSpot: go.Spot.Center, locationObjectName: "SHAPE",
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { rotatable: true, rotateObjectName: "SHAPE",
        locationSpot: go.Spot.Center, locationObjectName: "SHAPE",
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 },
        new go.Binding("angle").makeTwoWay()),  // TwoWay Binding of angle
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

You can customize the rotate handle by setting Part.rotateAdornmentTemplate. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { rotatable: true, rotateObjectName: "SHAPE",
        locationSpot: go.Spot.Center, locationObjectName: "SHAPE",
        rotateAdornmentTemplate:  // specify appearance of rotation handle
          $(go.Adornment,
            { locationSpot: go.Spot.Center, background: "transparent" },
            $(go.Shape, "BpmnActivityLoop",
              { width: 12, height: 12, stroke: "dodgerblue", strokeWidth: 2 })),
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

There are examples custom rotating tools defined in the samples and extensions directories: Rotate Multiple Tool (in Floor Plan Editor), Top Rotating Tool (in Draggable Link), 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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      $(go.Shape, "Rectangle",
        { fill: "lightgray", portId: "", fromLinkable: true, toLinkable: true }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );

  diagram.linkTemplate =
    $(go.Link,
      { relinkableFrom: true, relinkableTo: true },
      $(go.Shape),
      $(go.Shape, { toArrow: "Standard" })
    );

  var nodeDataArray = [
    { key: "Alpha" }, { key: "Beta" }, { key: "Gamma" }, { key: "Delta" }
  ];
  var linkDataArray = [
    { from: "Alpha", to: "Delta" }
  ];
  diagram.model = new go.GraphLinksModel(nodeDataArray, linkDataArray);

  diagram.select(diagram.findLinkForData(linkDataArray[0]));

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      new go.Binding("location", "loc", go.Point.parse),
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );

  diagram.linkTemplate =
    $(go.Link,
      { reshapable: true, routing: go.Link.Orthogonal },
      new go.Binding("points").makeTwoWay(),  // TwoWay Binding of Link.points
      $(go.Shape),
      $(go.Shape, { toArrow: "Standard" })
    );

  diagram.model = new go.GraphLinksModel([
    { key: "Alpha", loc: "0 0" },
    { key: "Beta", loc: "200 50" }
  ], [
    { from: "Alpha", to: "Beta" }
  ]);

  diagram.select(diagram.findLinkForData(diagram.model.linkDataArray[0]));

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. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      new go.Binding("location", "loc", go.Point.parse),
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );

  diagram.linkTemplate =
    $(go.Link,
      { reshapable: true, resegmentable: true, routing: go.Link.Orthogonal },
      new go.Binding("points").makeTwoWay(),  // TwoWay Binding of Link.points
      $(go.Shape),
      $(go.Shape, { toArrow: "Standard" })
    );

  diagram.model = new go.GraphLinksModel([
    { key: "Alpha", loc: "0 0" },
    { key: "Beta", loc: "200 50" }
  ], [
    { from: "Alpha", to: "Beta" }
  ]);

  diagram.select(diagram.findLinkForData(diagram.model.linkDataArray[0]));

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. You can change it. For example here is a drag-selecting box that is in the shape of a blue-outlined cloud. 

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.nodeTemplate =
    $(go.Node, "Auto",
      new go.Binding("location", "loc", go.Point.parse),
      $(go.Shape, "Rectangle", { fill: "lightgray" }),
      $(go.TextBlock, { margin: 5},
        new go.Binding("text", "key"))
    );

  diagram.toolManager.dragSelectingTool.isPartialInclusion = true;
  diagram.toolManager.dragSelectingTool.box =
    $(go.Part,
      { layerName: "Tool" },
      $(go.Shape, "Cloud",
        { name: "SHAPE", fill: null, stroke: "dodgerblue", strokeWidth: 2 })
    );

  diagram.model = new go.GraphLinksModel([
    { key: "Alpha", loc: "0 0" },
    { key: "Beta", loc: "200 50" }
  ], [
    { from: "Alpha", to: "Beta" }
  ]);

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. 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. 

  diagram.initialContentAlignment = go.Spot.Center;

  diagram.nodeTemplate =
    $(go.Node, "Spot",
      new go.Binding("location", "loc", go.Point.parse),
      $(go.Shape, "RoundedRectangle",
        { width: 100, height: 40, fill: "lightyellow",
          portId: "", fromLinkable: true, toLinkable: true, cursor: "pointer" }),
      $(go.TextBlock,
        new go.Binding("text", "key"))
    );

  diagram.toolManager.linkingTool.temporaryLink =
    $(go.Link,
      { layerName: "Tool" },
      $(go.Shape,
        { stroke: "red", strokeWidth: 2, strokeDashArray: [4, 2] })
    );

  var tempfromnode =
    $(go.Node,
      { layerName: "Tool" },
      $(go.Shape, "RoundedRectangle",
        { stroke: "chartreuse", strokeWidth: 3, fill: null,
          portId: "", width: 1, height: 1 })
    );
  diagram.toolManager.linkingTool.temporaryFromNode = tempfromnode;
  diagram.toolManager.linkingTool.temporaryFromPort = tempfromnode.port;

  var temptonode =
    $(go.Node,
      { layerName: "Tool" },
      $(go.Shape, "RoundedRectangle",
        { stroke: "cyan", strokeWidth: 3, fill: null,
          portId: "", width: 1, height: 1 })
    );
  diagram.toolManager.linkingTool.temporaryToNode = temptonode;
  diagram.toolManager.linkingTool.temporaryToPort = temptonode.port;

  diagram.model = new go.GraphLinksModel([
    { key: "Alpha", loc: "0 0" },
    { key: "Beta", loc: "200 50" },
    { key: "Gamma", loc: "400 0" }
  ]);  // start off with no links

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)