Panels

Panels are GraphObjects that hold other GraphObjects as their elements. A Panel is responsible for sizing and positioning all of its elements. Each Panel establishes its own coordinate system. The elements of a panel are drawn in order, thereby establishing the Z-ordering of those elements.

Although there is only one Panel class, there are many different kinds of panels, each with its own purpose in how it arranges its elements. When you construct a Panel you usually specify its Panel.type as the constructor argument. These are the kinds of panels that exist:

In these simplistic demonstrations, the code programmatically creates a Part and adds it to the Diagram. Once you learn about models and data binding you will generally not create parts programmatically.

Note also that one can only add Parts (i.e. Nodes and Links) to Diagrams, and that a Part cannot be an element of a Panel. But all Parts are Panels because the Part class inherits from Panel -- Parts are basically "top-level" Panels. Thus these examples make use of Parts as top-level objects whereas within a Node you would use a Panel instead of a Part.

Position Panels

The simplest kind of Panel is "Position" (Panel.Position). Each element gets its normal size, whether its natural size or a specified GraphObject.desiredSize (or equivalently the GraphObject.width and GraphObject.height).

Each element's position is given by the GraphObject.position property. If no position is specified, the element is positioned at (0,0). All positions are in the Panel's own coordinate system, not in the document-wide coordinate system. Positions may include negative coordinates.

The Panel's size is just big enough to hold all of its elements. If you want it to be a bit bigger than that, you can set the Panel.padding property. 

  diagram.add(
    // all Parts are Panels
    $(go.Part, go.Panel.Position,  // or "Position"
      { background: "lightgray" },
      $(go.TextBlock, "default, at (0,0)", { background: "lightgreen" }),
      $(go.TextBlock, "(100, 0)", { position: new go.Point(100, 0), background: "lightgreen" }),
      $(go.TextBlock, "(0, 100)", { position: new go.Point(0, 100), background: "lightgreen" }),
      $(go.TextBlock, "(55, 28)", { position: new go.Point(55, 28), background: "lightgreen" }),
      $(go.TextBlock, "(33, 70)", { position: new go.Point(33, 70), background: "lightgreen" }),
      $(go.TextBlock, "(100, 100)", { position: new go.Point(100, 100), background: "lightgreen" })
    ));

A Position Panel will always include the (0,0) origin point in its own panel coordinate system. Thus a Position Panel that has elements whose collective bounds does not include (0,0) is always extended to include the origin. 

  diagram.add(
    $(go.Part, "Position",
      { background: "lightgray" },
      $(go.TextBlock, "(-50,50)", { position: new go.Point(-50, 50), background: "lightgreen" }),
      $(go.TextBlock, "(50, 50)", { position: new go.Point(50, 50), background: "lightgreen" }),
      $(go.TextBlock, "(0, 100)", { position: new go.Point(0, 100), background: "lightgreen" })
    ));

Note that when you position Shapes within a Position Panel the thickness of their strokes, Shape.strokeWidth, will be included. If you wish to position multiple Shapes so that their geometries line up with each other, independent of how thick their strokes are, set Shape.isGeometryPositioned to true on each of those Shapes.

Vertical Panels

A very common kind of Panel is "Vertical" (Panel.Vertical). In this Panel all of the panel elements are arranged vertically from top to bottom. Each element gets its normal height and either its normal width or, if stretched, the width of the panel. If the element's GraphObject.stretch property has any vertical stretch component, it is ignored.

If the element's width does not happen to be the same as the width of the panel, it is aligned horizontally according to its GraphObject.alignment property.

The following Vertical Panel shows how narrow objects are aligned horizontally and how a narrow object may be stretched horizontally. The width of the whole Panel is determined by the width of the widest object, which in this case is the first element. Note how the last element does not set the desired GraphObject.width property, so that the GraphObject.stretch value is effective. 

  diagram.add(
    $(go.Part, go.Panel.Vertical,  // or "Vertical"
      { background: "lightgray" },
      $(go.TextBlock, "a longer string", { background: "lightgreen" }),
      $(go.TextBlock, "left", { background: "lightgreen", alignment: go.Spot.Left }),
      $(go.TextBlock, "center", { background: "lightgreen", alignment: go.Spot.Center }),
      $(go.TextBlock, "right", { background: "lightgreen", alignment: go.Spot.Right }),
      $(go.TextBlock, "stretch", { background: "lightgreen", stretch: go.GraphObject.Fill })
    ));

Constrained Width Vertical Panels

A Vertical Panel normally has the width of its widest element and the height that is the sum of all of its elements. However, you can also set the width and/or height to be larger or smaller than the natural size. Or if there is a Panel containing this panel, it might impose size constraints on this panel. If the width and/or height are larger than the natural size, the panel is bigger, leaving empty space that may be filled with the background brush. If the width and/or height are smaller than the natural size, the content elements may be clipped.

The Vertical Panel below sets the width to be 140, much wider than needed. You can see how the last element's width is stretched. 

  diagram.add(
    $(go.Part, "Vertical",
      { background: "lightgray", width: 140 },
      $(go.TextBlock, "a longer string", { background: "lightgreen" }),
      $(go.TextBlock, "left", { background: "lightgreen", alignment: go.Spot.Left }),
      $(go.TextBlock, "center", { background: "lightgreen", alignment: go.Spot.Center }),
      $(go.TextBlock, "right", { background: "lightgreen", alignment: go.Spot.Right }),
      $(go.TextBlock, "stretch", { background: "lightgreen", stretch: go.GraphObject.Fill })
    ));

These two Vertical Panels both have a width of 50, much less than natural. The latter one also has a restricted height. Note how the text is automatically wrapped to try to fit within the limited width, because the default value for TextBlock.wrap is to allow wrapping. 

  diagram.add(
    $(go.Part, "Vertical",
      { position: new go.Point(0, 0), background: "lightgray", width: 50 },
      $(go.TextBlock, "a longer string", { background: "lightgreen" }),
      $(go.TextBlock, "left", { background: "lightgreen", alignment: go.Spot.Left }),
      $(go.TextBlock, "center", { background: "lightgreen", alignment: go.Spot.Center }),
      $(go.TextBlock, "right", { background: "lightgreen", alignment: go.Spot.Right }),
      $(go.TextBlock, "stretch", { background: "lightgreen", stretch: go.GraphObject.Fill })
    ));
  diagram.add(
    $(go.Part, "Vertical",
      { position: new go.Point(70, 0), background: "lightgray", width: 50, height: 65 },
      $(go.TextBlock, "a longer string", { background: "lightgreen" }),
      $(go.TextBlock, "left", { background: "lightgreen", alignment: go.Spot.Left }),
      $(go.TextBlock, "center", { background: "lightgreen", alignment: go.Spot.Center }),
      $(go.TextBlock, "right", { background: "lightgreen", alignment: go.Spot.Right }),
      $(go.TextBlock, "stretch", { background: "lightgreen", stretch: go.GraphObject.Fill })
    ));

Here is a Vertical Panel with a default GraphObject.stretch of GraphObject.Horizontal. Because no width is specified for the whole panel, its width is the width of the widest element, in this case the second one. Note how all of the TextBlocks have the same long width, as highlighted by the lightgreen backgrounds. However the last TextBlock has a limited width, so it is not stretched. One can limit the width but not the height by supplying a value of NaN or Infinity for the height. 

  diagram.add(
    $(go.Part, "Vertical",
      { background: "lightgray", defaultStretch: go.GraphObject.Horizontal },
      $(go.TextBlock, "short", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "a much longer string", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "medium length", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "short2", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "max 50", { margin: 2, background: "lightgreen", maxSize: new go.Size(50, NaN) })
    ));

If you change that sample to set the GraphObject.width or GraphObject.desiredSize.width on one or more of the elements (just the last one in this case), the panel will get a width that is equal to the maximum of the set widths. The reduced width will cause the other, stretched, elements to be measured with the limited width (50 in this case), which cause those TextBlocks to wrap to fit within the available width. 

  diagram.add(
    $(go.Part, "Vertical",
      { background: "lightgray", defaultStretch: go.GraphObject.Horizontal },
      $(go.TextBlock, "short", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "a much longer string", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "medium length", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "short2", { margin: 2, background: "lightgreen" }),
      $(go.TextBlock, "= 50", { margin: 2, background: "lightgreen", width: 50 })
    ));

Horizontal Panels

Horizontal Panels are just like Vertical Panels, except that the elements are arranged horizontally instead of vertically. Elements are never stretched horizontally, but they may be stretched vertically. Because elements are never stretched horizontally, a stretch value of GraphObject.Fill is the same as GraphObject.Vertical.

Note that the last element in both panels do not specify a desired GraphObject.height, so that the GraphObject.stretch value may be effective. 

  diagram.add(
    $(go.Part, go.Panel.Horizontal,  // or "Horizontal"
      { position: new go.Point(0, 0), background: "lightgray" },
      $(go.Shape, { width: 30, fill: "lightgreen", height: 100 }),
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Top }),
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Center }),
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Bottom }),
      $(go.Shape, { width: 30, fill: "lightgreen", stretch: go.GraphObject.Fill })
    ));
  diagram.add(
    $(go.Part, "Horizontal",
      { position: new go.Point(200, 0), background: "lightgray", height: 120 },
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Top }),
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Center }),
      $(go.Shape, { width: 30, fill: "lightgreen", height: 50, alignment: go.Spot.Bottom }),
      $(go.Shape, { width: 30, fill: "lightgreen", stretch: go.GraphObject.Fill })
    ));

Filling Horizontal and Vertical Panels in Opposite Direction

Both Vertical and Horizontal Panels can have their elements be arranged in the opposite direction: bottom-to-top for Vertical Panels and right-to-left for Horizontal Panels. Just set Panel.isOpposite to true. 

  diagram.add(
    $(go.Part, "Horizontal",
      { background: "lightgray", isOpposite: true },
      $(go.TextBlock, "0", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "1", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "2", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "3", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "4", { margin: 5, background: "lightgreen" })
    ));

  diagram.add(
    $(go.Part, "Vertical",
      { background: "lightgray", isOpposite: true },
      $(go.TextBlock, "0", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "1", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "2", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "3", { margin: 5, background: "lightgreen" }),
      $(go.TextBlock, "4", { margin: 5, background: "lightgreen" })
    ));

Default Alignment and Stretch

Both Vertical and Horizontal Panels support the Panel.defaultAlignment and Panel.defaultStretch properties. This is a convenience so that you do not need to set the GraphObject.alignment or GraphObject.stretch property on each element.

Here is a Horizontal Panel with a default GraphObject.alignment of Spot.Bottom. All of the Shapes are aligned at the bottom, even though the default alignment would normally be Spot.Center. However, the last Shape has its height stretched to the full height of the panel, 90. In this case the GraphObject.margin provides a little extra space around the object. 

  diagram.add(
    $(go.Part, "Horizontal",
      { background: "lightgray", height: 90, defaultAlignment: go.Spot.Bottom },
      $(go.Shape, { width: 30, margin: 2, fill: "lightgreen", height: 60 }),
      $(go.Shape, { width: 30, margin: 2, fill: "lightgreen", height: 30 }),
      $(go.Shape, { width: 30, margin: 2, fill: "lightgreen", height: 40 }),
      $(go.Shape, { width: 30, margin: 2, fill: "lightgreen", stretch: go.GraphObject.Fill })
    ));

Vertical and Horizontal Panels are relatively simple ways of arranging a column or a row of objects. For more options, you may need to use a Table Panel, even with the same set of objects. This is especially true when you want more control over the stretching of one or more elements.

Spots

Before we discuss other kinds of Panels, we should elaborate a bit about the concept of spots. Spots are a way of providing both relative and absolute positioning information.

You have already seen many of the most common uses of Spots, for specifying the alignment of objects within a panel, as constant values of the Spot class:

Spot.TopLeft Spot.Top Spot.TopRight
Spot.Left Spot.Center Spot.Right
Spot.BottomLeft Spot.Bottom Spot.BottomRight

But Spots are more general than that. The Spot.x and Spot.y properties can be any number between zero and one, inclusive. Those values are the fractional distances along the X and Y axes from the top-left corner of an arbitrary rectangle. So Spot.TopLeft is the same as new go.Spot(0, 0), Spot.BottomRight is the same as new go.Spot(1, 1), and Spot.Right is the same as new go.Spot(1, 0.5).

Here are the standard nine Spots shown on a rectangular shape. 

  diagram.add(
    $(go.Part, go.Panel.Spot,  // or "Spot"
      $(go.Shape, "Rectangle",
        { fill: "lightgreen", stroke: null, width: 100, height: 50 }),
      $(go.TextBlock, "0,0",     { alignment: new go.Spot(0, 0) }),
      $(go.TextBlock, "0.5,0",   { alignment: new go.Spot(0.5, 0) }),
      $(go.TextBlock, "1,0",     { alignment: new go.Spot(1, 0) }),
      $(go.TextBlock, "0,0.5",   { alignment: new go.Spot(0, 0.5) }),
      $(go.TextBlock, "0.5,0.5", { alignment: new go.Spot(0.5, 0.5) }),
      $(go.TextBlock, "1,0.5",   { alignment: new go.Spot(1, 0.5) }),
      $(go.TextBlock, "0,1",     { alignment: new go.Spot(0, 1) }),
      $(go.TextBlock, "0.5,1",   { alignment: new go.Spot(0.5, 1) }),
      $(go.TextBlock, "1,1",     { alignment: new go.Spot(1, 1) })
    ));

Besides the fractional positioning of a spot relative to some rectangular area, you can also specify an absolute offset. The Spot.offsetX and Spot.offsetY properties determine a point that is a distance from the fractional point given by Spot.x and Spot.y. Here we show three TextBlocks near the bottom-left corner and three TextBlocks near the bottom-right corner. The ones on the left are offset along the X-axis plus or minus 40 units; the ones on the right are offset along the Y-axis plus or minus 20 units. TextBlocks are also given a semi-transparent red background to help distinguish their bounds. 

  var pink = "rgba(255,0,0,.2)";
  diagram.add(
    $(go.Part, "Spot",
      $(go.Shape, "Rectangle",
        { fill: "lightgreen", stroke: null, width: 200, height: 50 }),

      // Near bottom-left corner:
      $(go.TextBlock, "(-40,0)",  { background: pink, alignment: new go.Spot(0, 1, -40, 0) }),
      $(go.TextBlock, "(0,0)",    { background: pink, alignment: new go.Spot(0, 1, 0, 0) }),
      $(go.TextBlock, "(40,0)",   { background: pink, alignment: new go.Spot(0, 1, 40, 0) }),

      // Near bottom-right corner:
      $(go.TextBlock, "(0,-20)",  { background: pink, alignment: new go.Spot(1, 1, 0, -20) }),
      $(go.TextBlock, "(0,0)",    { background: pink, alignment: new go.Spot(1, 1, 0, 0) }),
      $(go.TextBlock, "(0,20)",   { background: pink, alignment: new go.Spot(1, 1, 0, 20) })
    ));

Auto Panels

Auto Panels fit a "main" element just around the other elements of the panel. The main element is usually the furthest back in the Z-order, i.e. the first element, so that the other elements are not obscured by it. The main element is declared by setting GraphObject.isPanelMain to true; but often no such element is present, so it uses the very first element of the panel.

Typically the Auto Panel will measure the non-"main" elements, determine a width and a height that can enclose all of them, and make the "main" element that size or slightly bigger. You do not set the GraphObject.desiredSize (or GraphObject.width or GraphObject.height) of the "main" element.

An Auto Panel is the normal way to implement a border around an object. Use a Shape as the first/"main" element -- it becomes the border. The Shape.figure is normally "Rectangle" or "RoundedRectangle" or "Ellipse", as shown below. The other elements become the "content" for the panel inside the border. In the examples below there is only a single "content" element, a TextBlock. We have set the GraphObject.background and Shape.fill properties to help show the sizes and positions of objects.

Auto Panels should have two or more elements in them. 

  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(0, 0), background: "lightgray" },
      $(go.Shape, "Rectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(100, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(200, 0), background: "lightgray" },
      $(go.Shape, "Ellipse", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));

If you add a GraphObject.margin to the TextBlock in each of the same three panels, you will add a little space all around the "content" element inside the "main" element. 

  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(0, 0), background: "lightgray" },
      $(go.Shape, "Rectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { margin: 2, background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(100, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { margin: 2, background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(200, 0), background: "lightgray" },
      $(go.Shape, "Ellipse", { fill: "lightgreen" }),
      $(go.TextBlock, "some text", { margin: 2, background: "yellow" })
    ));

For most Shapes other than "Rectangle" figure we do not want to have the "main" shape be the same size as the "content" element. Ellipses, for example, need to be significantly larger than the content to avoid having the content spill over the edge of the shape. This can be controlled by setting the Shape.spot1 and Shape.spot2 properties, which determine the area where the content should go. Many of the predefined figures have their own default values for spot1 and spot2. 

  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(0, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle",
        { fill: "lightgreen", spot1: new go.Spot(0, 0), spot2: new go.Spot(1, 1) }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(100, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle",
        { fill: "lightgreen",
          spot1: new go.Spot(0, 0, 10, 0), spot2: new go.Spot(1, 1, -10, -10) }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(200, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle",
        { fill: "lightgreen",
          spot1: new go.Spot(0, 0, 0, 20), spot2: new go.Spot(1, 1, 0, -20) }),
      $(go.TextBlock, "some text", { background: "yellow" })
    ));

The spot1 and spot2 properties on the main Shape are more general and more flexible than specifying the GraphObject.margin on the content element(s).

Constrained Size Auto Panels

If you constrain the size of the whole panel, there may be less or more space available to fit all of the "content" elements inside the "main" element. In the following example each Part has a total size of 50x50, causing the "content" TextBlocks to be limited in width and height, less than the natural width, which results in wrapping of the text. However there may not be enough height available to show the whole content element(s), causing them to be clipped. You can see that in the third Part the text is clipped, because there is less available area within an ellipse than within a rectangle. 

  diagram.add(
    $(go.Part, "Auto",
      { width: 60, height: 60 },  // set the size of the whole panel
      { position: new go.Point(0, 0), background: "lightgray" },
      $(go.Shape, "Rectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "Some Wrapping Text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { width: 60, height: 60 },  // set the size of the whole panel
      { position: new go.Point(100, 0), background: "lightgray" },
      $(go.Shape, "RoundedRectangle", { fill: "lightgreen" }),
      $(go.TextBlock, "Some Wrapping Text", { background: "yellow" })
    ));
  diagram.add(
    $(go.Part, "Auto",
      { width: 60, height: 60 },  // set the size of the whole panel
      { position: new go.Point(200, 0), background: "lightgray" },
      $(go.Shape, "Ellipse", { fill: "lightgreen" }),
      $(go.TextBlock, "Some Wrapping Text", { background: "yellow" })
    ));

You should not set the size (GraphObject.desiredSize or GraphObject.width or GraphObject.height) of the "main" element of an Auto Panel.

Auto Panels should have two or more elements in them.

Spot Panels

Spot Panels are like Auto Panels in that there is a "main" element and there are "other" elements that are not resized. The "other" elements are positioned about the "main" element based on the GraphObject.alignment property that has a Spot value. The main feature of Spot Panels, unlike Auto Panels, is that those elements may extend beyond the bounds of the "main" element.

This is useful for having the main shape be a specific size and positioning smaller elements at particular places relative to the main shape. Note in this example that the TextBlocks are centered at the four corners, causing the panel to be larger than the main shape, as can be seen with the light gray background. 

  diagram.add(
    $(go.Part, "Spot",
      { background: "lightgray" },
      $(go.Shape, "Rectangle",
        { fill: "lightgreen", width: 100, height: 50 }),
      $(go.TextBlock, "TL", { background: "yellow", alignment: go.Spot.TopLeft }),
      $(go.TextBlock, "TR", { background: "yellow", alignment: go.Spot.TopRight }),
      $(go.TextBlock, "BL", { background: "yellow", alignment: go.Spot.BottomLeft }),
      $(go.TextBlock, "BR", { background: "yellow", alignment: go.Spot.BottomRight })
    ));

A Spot Panel aligns its content elements in the general location given by its GraphObject.alignment. The precise point in the content element that is positioned defaults to Spot.Center, as seen above. But you can set the element's GraphObject.alignmentFocus to use a different spot. For example, if you use the same alignmentFocus as the alignment, the elements will be just inside the main element's bounds: 

  diagram.add(
    $(go.Part, "Spot",
      { background: "lightgray" },
      $(go.Shape, "Rectangle",
        { fill: "lightgreen", width: 100, height: 50 }),
      $(go.TextBlock, "TL", { background: "yellow",
                        alignment: go.Spot.TopLeft, alignmentFocus: go.Spot.TopLeft }),
      $(go.TextBlock, "TR", { background: "yellow",
                        alignment: go.Spot.TopRight, alignmentFocus: go.Spot.TopRight }),
      $(go.TextBlock, "BL", { background: "yellow",
                        alignment: go.Spot.BottomLeft, alignmentFocus: go.Spot.BottomLeft }),
      $(go.TextBlock, "BR", { background: "yellow",
                        alignment: go.Spot.BottomRight, alignmentFocus: go.Spot.BottomRight })
    ));

If you use the opposite alignmentFocus as the alignment, the elements will be just outside the main element's bounds: 

  diagram.add(
    $(go.Part, "Spot",
      { background: "lightgray" },
      $(go.Shape, "Rectangle",
        { fill: "lightgreen", width: 100, height: 50 }),
      $(go.TextBlock, "TL", { background: "yellow",
                        alignment: go.Spot.TopLeft, alignmentFocus: go.Spot.BottomRight }),
      $(go.TextBlock, "TR", { background: "yellow",
                        alignment: go.Spot.TopRight, alignmentFocus: go.Spot.BottomLeft }),
      $(go.TextBlock, "BL", { background: "yellow",
                        alignment: go.Spot.BottomLeft, alignmentFocus: go.Spot.TopRight }),
      $(go.TextBlock, "BR", { background: "yellow",
                        alignment: go.Spot.BottomRight, alignmentFocus: go.Spot.TopLeft })
    ));

If you constrain the size of the whole panel, the panel may clip its elements. For example, when the whole panel must be 100x50, there is room horizontally but not vertically for the main element plus all of its other elements after arranging them. 

  diagram.add(
    $(go.Part, "Spot",
      { background: "lightgray",
                    width: 100, height: 50 },  // it is unusual to set the size!
      $(go.Shape, "Rectangle", { fill: "lightgreen", width: 40, height: 40 }),
      $(go.TextBlock, "TL", { background: "yellow",
                        alignment: go.Spot.TopLeft, alignmentFocus: go.Spot.BottomRight }),
      $(go.TextBlock, "TR", { background: "yellow",
                        alignment: go.Spot.TopRight, alignmentFocus: go.Spot.BottomLeft }),
      $(go.TextBlock, "BL", { background: "yellow",
                        alignment: go.Spot.BottomLeft, alignmentFocus: go.Spot.TopRight }),
      $(go.TextBlock, "BR", { background: "yellow",
                        alignment: go.Spot.BottomRight, alignmentFocus: go.Spot.TopLeft })
    ));

Spot Panels should have two or more elements in them.

Remember that the elements of every panel are drawn in order. Normally you want the main element to be behind all of the other elements, so the main element will come first. However if you want the main element to be in front of some or all of the other elements, you can move the main element not to be the first element of the panel, if you also set its GraphObject.isPanelMain property to true. 

  diagram.add(
    $(go.Part, "Spot",
      { background: "lightgray" },
      $(go.TextBlock, "TL", { background: "yellow", alignment: go.Spot.TopLeft }),
      $(go.TextBlock, "TR", { background: "yellow", alignment: go.Spot.TopRight }),
      $(go.TextBlock, "BL", { background: "yellow", alignment: go.Spot.BottomLeft }),
      $(go.TextBlock, "BR", { background: "yellow", alignment: go.Spot.BottomRight }),

      // NOTE: the main element isn't first, so it must be declared by setting isPanelMain to true
      $(go.Shape, "Rectangle",
        { isPanelMain: true },
        { fill: "lightgreen", width: 100, height: 50 })
    ));

Note how the opaque Shape, explicitly declared to be the main element, is now visually in front of the non-main elements of the Spot Panel because it has been moved to be the last element in the panel.

Without setting GraphObject.isPanelMain to true on the desired main element, in this example Panel.findMainElement would return the first TextBlock. This would cause all of the other elements to be arranged around that TextBlock. Since the TextBlock is small and the rectangular Shape is big and opaque, the Shape would cover all of the other TextBlocks, so the user might not see any text, depending on the size and alignment of those other TextBlocks.

Clipping with Spot Panels

Spot Panels can set Panel.isClipping to true to use the main Panel element as a clipping area instead of a drawn Shape. If used, the main element must be a Shape and its stroke and fill will not be drawn.

Example: 

  diagram.layout = $(go.GridLayout);
  diagram.initialContentAlignment = go.Spot.Center;

  // Without Panel.isClipping
  diagram.add(
    $(go.Part, "Spot",
      { scale: 2  },
      $(go.Shape, "Circle", { width: 55, height: 55, strokeWidth: 0 } ),
      $(go.Picture, "../samples/images/55x55.png",
        { width: 55, height: 55 }
       )
    )
  );

  // Using Panel.isClipping
  diagram.add(
    $(go.Part, "Spot",
      { isClipping: true, scale: 2  },
      $(go.Shape, "Circle", { width: 55, height: 55, strokeWidth: 0 } ),
      $(go.Picture, "../samples/images/55x55.png",
        { width: 55, height: 55 }
       )
    )
  );

  // Using Panel.isClipping and also having a surrounding panel
  diagram.add(
    $(go.Part, "Spot",
      { scale: 2 },
      $(go.Shape, "Circle", { width: 65, height: 65, strokeWidth: 0, fill: 'red' } ),
      $(go.Panel, "Spot",
        { isClipping: true  },
        $(go.Shape, "Circle", { width: 55, height: 55, strokeWidth: 0 } ),
        $(go.Picture, "../samples/images/55x55.png",
          { width: 55, height: 55 }
         )
      )
    )
  );

Viewbox Panels

Viewbox Panels contain only a single element that is rescaled to fit the size of the Panel.

This is useful for taking an arbitrary element, especially a Panel, and automatically squeezing it to fit in a small fixed-size area. The same can be achieved by setting the GraphObject.scale on that element, but with a Viewbox Panel that computation is performed automatically.

In this diagram there are two copies of the same Auto Panel, each consisting of a Picture and a caption TextBlock surrounded by an Ellipse Shape. The one on the left is inside a Viewbox Panel forced to fit in an 80x80 area; the one on the right is its natural size. Note that you can still see all of the elements of the panel at a reduced scale so that it can fit inside the Viewbox panel. But because the nested panel is taller than it is wider, there is empty space on the sides of the 80x80 Viewbox. 

  diagram.add(
    $(go.Part, go.Panel.Viewbox,  // or "Viewbox"
      { position: new go.Point(0, 0), background: "lightgray",
        width: 80, height: 80 },
      $(go.Panel, "Auto",
        $(go.Shape, "Ellipse", { fill: "lightgreen" }),
        $(go.Panel, "Vertical",
          $(go.Picture, { source: "images/120x160.png" }),
          $(go.TextBlock, "a 120x160 kitten")
        )
      )
    ));
  diagram.add(
    $(go.Part, "Auto",
      { position: new go.Point(100, 0), background: "lightgray" },
      $(go.Shape, "Ellipse", { fill: "lightgreen" }),
      $(go.Panel, "Vertical",
        $(go.Picture, { source: "images/120x160.png" }),
        $(go.TextBlock, "a 120x160 kitten")
      )
    ));