GoJS Tools -- Northwoods Software

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 and keyboard) 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.

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:

ToolManager.actionTool, an ActionTool, for allowing "buttons" and other GraphObjects to grab events from the regular tools
ToolManager.relinkingTool, a RelinkingTool, for reconnecting an existing Link
ToolManager.linkReshapingTool, a LinkReshapingTool, for changing the route of a Link
ToolManager.resizingTool, a ResizingTool, for changing the GraphObject.desiredSize of a Part or an object within a Part
ToolManager.rotatingTool, a 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:

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

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

ToolManager.contextMenuTool, a ContextMenuTool, for showing a context menu for a GraphObject
ToolManager.textEditingTool, a TextEditingTool, for in-place editing of TextBlocks in selected Parts
ToolManager.clickCreatingTool, a ClickCreatingTool, for inserting a new Part when the user clicked
ToolManager.clickSelectingTool, a 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.

For example, to disable the rubber-band selection tool (DragSelectingTool), set diagram.toolManager.dragSelectingTool.isEnabled = false;.
You can change the appearance of a selected Part (actually its selection Adornment) by setting Part.selectionAdornmentTemplate. (See Selection for more discussion.)
You can enable users to draw new links interactively (LinkingTool) by setting GraphObject.fromLinkable and GraphObject.toLinkable on the port objects of your nodes.
You can disable the movement of a Node (DraggingTool) by setting Part.movable to false.
You can disable resizing any part (ResizingTool) by setting Diagram.allowResize to false.
Tooltips, implemented by the ToolManager, are discussed in ToolTips.
Context menus, implemented by the ContextMenuTool, are discussed in Context Menus.

More detail is available in the section about Permissions.

Some commonly set properties include:

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

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

If you want to let the user resize the whole node, just set Part.resizable to true.

  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.

  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 }),
      $(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.

  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,
          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),
        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();

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 cyan rectangular Shapes, each representing a handle.

  diagram.initialContentAlignment = go.Spot.Center;
  diagram.add(
    $(go.Node, "Vertical",
      { resizable: true, resizeObjectName: "SHAPE",
        resizeAdornmentTemplate:
          $(go.Adornment, "Spot",
            $(go.Placeholder),  // takes size and position of adorned object
            $(go.Shape,  // left resize handle
              { alignment: go.Spot.Left, cursor: "col-resize",
                desiredSize: new go.Size(6, 6), fill: "lightblue", stroke: "dodgerblue" }),
            $(go.Shape,  // right resize handle
              { alignment: go.Spot.Right, cursor: "col-resize",
                desiredSize: new go.Size(6, 6), fill: "lightblue", stroke: "dodgerblue" })),
        selectionAdorned: false },
      $(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.

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.

  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.

  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 }),
      $(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:
          $(go.Adornment,
            { locationSpot: go.Spot.Center, background: "transparent" },
            $(go.Shape, "BpmnActivityLoop",
              { width: 12, height: 12, stroke: "blue", strokeWidth: 2 })),
        selectionObjectName: "SHAPE" },
      $(go.Shape, "RoundedRectangle",
        { name: "SHAPE", fill: "orange", width: 50, height: 30 }),
      $(go.TextBlock, "Hello!", { margin: 3 })
    ));
  diagram.commandHandler.selectAll();

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

  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" }
  ];
  var linkDataArray = [
    { from: "Alpha", to: "Beta" }
  ];
  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.

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.

  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 },
      $(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.

  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 },
      $(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 are even smaller blue diamonds. They can be customized by setting LinkReshapingTool.midHandleArchetype. At the current time they cannot be customized by setting a property on the Link.

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 it expects that the object to be resized by the tool to be 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.

LinkingTool and RelinkingTool

The linking tools, LinkingTool and RelinkingTool, inherit from a base class, LinkingBaseTool, that uses several Parts as a temporary Link and as 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.