Initial, Automatic, and Programmatic Viewport Management

Once you have created and assigned a model to cause some Parts to appear in your Diagram, you can control where your parts initially appear in the viewport, and you can control where they are shown after the diagram has been modified.

Initial viewport

You can very easily set the Diagram.initialPosition and/or Diagram.initialScale properties at any time, even before assigning the model. This will cause the Diagram.position and/or Diagram.scale properties to be set to the specified initial value(s) once all of the Parts have been created and any initial layout has been performed.

But what if you do not know how big your diagram document will be? If you want to show a particular area of the document, you will not know what position to set. If you want to show a big document at the largest scale that shows all of it, you will not know what scale to set.

One solution to this problem is to set the Diagram.initialDocumentSpot and Diagram.initialViewportSpot properties to particular Spot values. For example, if you are showing a tree-like diagram and you want tree to be centered horizontally but positioned vertically at the top, you can do something like this when you create the Diagram:


  new go.Diagram("myDiagramDiv",
    {
      initialDocumentSpot: go.Spot.Top,
      initialViewportSpot: go.Spot.Top
    })

This makes sure that after the initial layout of your diagram the middle top point of the diagram contents is positioned to be at the middle top point of the viewport.

Another solution to this problem is to set the Diagram.initialContentAlignment or Diagram.initialAutoScale properties. For example it is fairly common to want to make sure that small documents appear top-centered within the diagram window -- just set Diagram.initialContentAlignment to Spot.Top. Or if you want to "zoom-to-fit" the diagram, just set Diagram.initialAutoScale to AutoScale.Uniform.


  new go.Diagram("myDiagramDiv",
    {
      initialAutoScale: go.AutoScale.Uniform
    })

More generally, you may want to try to center a particular Node. Here is how you can do that:


  // allow the diagram to be scrolled a bit beyond the document bounds
  diagram.scrollMargin = 100;

  diagram.nodeTemplate =
    new go.Node("Auto")
      .bind("location", "loc")
      .add(
        new go.Shape({ fill: "lightyellow" }),
        new go.TextBlock({ margin: 5 })
          // show the location as text in the node
          .bind("text", "loc",
                p => p.x.toFixed() + ", " + p.y.toFixed())
      );

  // initialize the model with random nodes:
  const nodeDataArray = [];
  for (let i = 0; i < 20; i++ ) {
    nodeDataArray.push({ loc: new go.Point(Math.random() * 600, Math.random() * 300) });
  }
  diagram.model.nodeDataArray = nodeDataArray;

  // this event handler is called when the diagram is first ready
  diagram.addDiagramListener("InitialLayoutCompleted", e => {
    // pick a random node data
    const data = nodeDataArray[Math.floor(Math.random()*nodeDataArray.length)];
    // find the corresponding Node
    const node = diagram.findNodeForData(data);
    // and center it and select it
    diagram.centerRect(node.actualBounds);
    diagram.select(node);
  });

Note: because by default one cannot scroll past any edge of the document plus any Diagram.scrollMargin, if the selected node happens to be at or near an edge, the node cannot actually be centered in the viewport unless you set Diagram.scrollMode, Diagram.scrollMargin, or Diagram.padding.

Automatic viewport management

There are also times when you will want to control the viewport (i.e. the Diagram.position and Diagram.scale) after every change to the diagram. For example, if you always want to keep the document centered after the user has moved or deleted or inserted nodes, set Diagram.contentAlignment (rather than Diagram.initialContentAlignment) to Spot.Center.

Or if you always want to keep the document "zoomed-to-fit", set Diagram.autoScale (rather than Diagram.initialAutoScale) to AutoScale.Uniform. As an example, the Overview diagram does this.

Programmatic viewport management

If you do not want continual repositioning or rescaling of the diagram, but you do sometimes want to change the Diagram.position and/or the Diagram.scale, you can set those properties to whatever values you like. However, please note that the ultimate value for Diagram.position is normally limited by the Diagram.documentBounds and the size of the viewport and the scale of the diagram. The Diagram.scale is limited by Diagram.minScale and Diagram.maxScale.

But it is more common to call a method on Diagram to achieve the results that you want. For example, to get the effect of the Diagram.initialDocumentSpot and Diagram.initialViewportSpot properties that are used when the "InitialLayoutCompleted" DiagramEvent occurs, call Diagram.alignDocument with the two desired Spots that you want to have coincide.

As already demonstrated above, if you want to try to center a particular node in the viewport, you can call Diagram.centerRect with the node's GraphObject.actualBounds.

If you want to make sure that a particular node is within the viewport, but not necessarily centered, call Diagram.scrollToRect.

If you just want to scroll the diagram, in the same manners as the user might via a scrollbar or the mouse wheel, call Diagram.scroll with arguments that specify how much to scroll and in which direction.

The just-mentioned Diagram methods do not change the Diagram.scale. If you want to rescale the diagram so that the whole document bounds are shown, call Diagram.zoomToFit. More generally, if you want a particular area of your diagram to be shown at whatever scale will make it fit in the viewport, call Diagram.zoomToRect.