Panel class

A Panel is a GraphObject that holds other GraphObjects as its elements. A Panel is responsible for sizing and positioning its elements. The elements of a panel are drawn in the order in which they appear in the #elements collection.

The Part class inherits from Panel; Part in turn is the base class of Node and Link.

Every Panel has a #type and establishes its own coordinate system. The type of a Panel determines how it will size and arrange its elements:

• Panel.Position is used to arrange elements based on their absolute positions within the Panel's local coordinate system.
• Panel.Vertical and Panel.Horizontal are used to create linear "stacks" of elements.
• Panel.Auto is used to size the main element to fit around other elements in the Panel -- this creates borders.
• Panel.Spot is used to arrange elements based on the Spot properties GraphObject#alignment and GraphObject#alignmentFocus, relative to a main element of the panel. Spot panels can align relative to other elements by using Panel#alignmentFocusName.
• Panel.Table is used to arrange elements into rows and columns, typically employing the different elements' GraphObject#row, GraphObject#rowSpan, GraphObject#column, and GraphObject#columnSpan properties. This Panel type also makes use of RowColumnDefinition.
• Panel.TableRow and Panel.TableColumn can only be used immediately within a Panel.Table Panel to organize a collection of elements as a row or as a column in a table.
• Panel.Viewbox is used to automatically resize a single element to fit inside the panel's available area.
• Panel.Grid is not used to house typical elements, but is used only to draw regular patterns of lines. The elements must be Shapes used to describe the repeating lines.
• Panel.Link is only used by Link parts and Link Adornments.
• Panel.Graduated is used to draw regular tick marks and text along the main Shape element.

Using GraphObject.make, the second argument can be used to declare the Panel type. The second argument may also be an instance of PanelLayout, if you want to use a custom panel layout.

// Either:
new go.Panel(go.Panel.Horizontal, ...
// Or:
new go.Panel("Horizontal", ...

// Full example:
p = new go.Panel("Horizontal",
  { width: 60, height: 60 }) // panel properties
  // elements in the panel:
  .add(new go.Shape("Rectangle", { stroke: "lime" }))
  .add(new go.TextBlock("Some Text"))

For an overview of most Panel types, please read the Introduction page on Panels.

Panel.Vertical and Panel.Horizontal panels are frequently used to position two or more GraphObjects vertically above each other or horizontally next to each other. Use the GraphObject#alignment or GraphObject#stretch properties on the individual elements to control their position and size. Set #isOpposite to true if you want the elements arranged from right-to-left in Horizontal Panels or from bottom-to-top in Vertical Panels.

Panel.Spot and Panel.Auto panels have a "main" element, signified by the Panel's first element with GraphObject#isPanelMain set to true. If there is no such element, it uses the first element as the "main" one. Use the GraphObject#alignment property to position elements with respect to the main element. Use the GraphObject#alignmentFocus property to further specify the position within Spot Panels. "Spot" and "Auto" Panels should have two or more elements in them.

In Panel.Table panels you will want to set the GraphObject#row and GraphObject#column properties on each element. The GraphObject#alignment and GraphObject#stretch properties are also useful when an element's table cell is larger than that element.

Please read the Introduction page on Table Panels for more examples and explanation.

Panel.TableRow and Panel.TableColumn panels can only be used as elements within a Panel.Table Panel. They are typically only used in item templates, e.g. for automatically creating rows in a Table Panel based on model data provided in an #itemArray. You will still need to specify properties on the individual elements within a TableRow or TableColumn as if they were immediate elements of the containing Table panel.

For an example that uses TableRow Panels, see Records sample.

Panel.Grid panels are often used for the Diagram's Diagram#grid.

const diagram = new go.Diagram("myDiagramDiv",
  // Diagram options:
  { . . .
    grid: new go.Panel("Grid",
            { gridCellSize: new go.Size(40, 40) })
            .add(new go.Shape("LineH", { stroke: "lightgray" }))
            .add(new go.Shape("LineV", { stroke: "lightgray" })),
    . . .
  });

Or to get a green bar effect:

 const diagram = new go.Diagram("myDiagramDiv",
  { . . .
    grid: new go.Panel("Grid",
            { gridCellSize: new go.Size(100, 100) })
            .add(new go.Shape("BarH", { fill: "lightgreen", height: 50 })),
    . . .
  });

But Grid Panels can also be stand alone objects:

new go.Node("Grid",
  { gridCellSize: new go.Size(6, 6), width: 60, height: 60 })
  .add(new go.Shape("LineH", { stroke: "gray" }))
  .add(new go.Shape("LineV", { stroke: "gray" }))

A Grid Panel's elements do not participate in object picking.

Please read the Introduction page on Grid Patterns for more examples and explanation.

Panel.Graduated panels, like Spot and Auto Panels have a "main" element. The other elements within a Graduated Panel are used to define ticks and labels to draw along the main shape's path.

new go.Part("Graduated")
  .add(new go.Shape({ geometryString: "M0 0 H400" }))
  .add(new go.Shape({ geometryString: "M0 0 V10" }))
  // offset to display below ticks
  .add(new go.TextBlock({ segmentOffset: new go.Point(0, 12) }));

Only the main shape of a Graduated Panel participates in object picking, but a background can be set if the entire panel needs to be pickable. You cannot set or bind the Panel#itemArray of a Graduated Panel. Events on the tick Shapes and TextBlock labels of a Graduated Panel will be ignored. Graduated Panel TextBlock labels cannot be edited.

Rotating the main shape will not rotate the ticks, just as rotating a Spot Panel's main element won't rotate its children. Rotation should generally be done at the Panel level. Another similarity to Spot Panels is that resizing of a Graduated Panel should generally be done on the main shape.

Please read the Introduction page on Graduated Panels for more examples and explanation.

Changing and accessing elements of a Panel

You can change the collection of #elements by calling #add, #insertAt, #remove, or #removeAt. You can get direct access to a particular element by calling #elt.

Alternatively you can control the number and order of elements that are copies of an item template by setting or binding the #itemArray property. This is discussed below.

You can search the visual tree of a Panel for GraphObjects that given a GraphObject#name using #findObject.

Panel Size and Appearance

Panels typically compute their own size based on their elements and Panel #type, but can also be sized by setting GraphObject#desiredSize, GraphObject#minSize, and GraphObject#maxSize. Setting an explicit size on a Panel may cause nested elements of that panel to size themselves differently, especially in the cases of nested elements having a GraphObject#stretch value or TextBlock's having word wrap.

Panels have no visual components of their own unless a GraphObject#background is specified or separators are specified either as defaults for the whole Table Panel or on individual RowColumnDefinitions. Panels can specify #padding, to make the Panel larger including its background. Setting a padding when the Panel is constrained in size will reduce the total area that it has to arrange its elements. Setting a #margin will not do this -- instead the Panel will expand in size.

In addition to the GraphObject properties on elements that are only used by certain types of panels, several Panel properties only apply to specific Panel types.

• Panels of #type Panel.Table use the #rowCount, #rowSizing, #columnCount, #columnSizing, #leftIndex, #topIndex, and all of the "default" separator properties.
• Panels of #type Panel.TableRow and Panel.TableColumn do not act like regular GraphObjects, instead they are only to be used immediately within a Panel.Table. They are pass-through containers that hold elements for their parent table, and ignore their own scale and angle.
• Panels of #type Panel.Grid use the #gridCellSize and #gridOrigin properties.
• Panels of #type Panel.Viewbox use the #viewboxStretch property.
• Panels of #type Panel.Graduated use the #graduatedMin, #graduatedMax, #graduatedTickUnit, and #graduatedTickBase properties.

For live examples of all Panel types, see the Introduction page on Panels.

Data Binding

Panels also provide fundamental support for data binding. When a diagram gets a new model or when a diagram's model is augmented with additional data, the diagram automatically creates a new Node or Link whose #data property refers to the corresponding node data or link data object.

For more discussion of data binding, please read the Introduction page on Models and Data Binding.

Panels provide support for automatically creating elements within the Panel based on items in a JavaScript Array. This is achieved by setting or binding the #itemArray property, which acts in a manner similar to the Model#nodeDataArray property. You can supply an #itemTemplate, which must itself be a simple Panel, which is copied to create the element in this container Panel corresponding to an item in the itemArray. This property is analogous to the Diagram#nodeTemplate property, although for the diagram the template must be a Node, Group, or simple Part.

Much like the Diagram#nodeTemplateMap, Panel's #itemTemplateMap supports having multiple templates, so that the actual structure of the element created for a data item can be chosen dynamically. Just as the Model#nodeCategoryProperty determines which template in the Diagram#nodeTemplateMap is copied to create a Node, the #itemCategoryProperty names the data property whose value chooses the Panel in the itemTemplateMap to copy for the item.

When binding the #itemArray property, it is commonplace to set Model#copiesArrays and Model#copiesArrayObjects properties to true, so that when a node is copied, the item Array and its contents are copied, not shared. Or more generally, to customize the model's copying processes, you can supply a custom Model#copyNodeDataFunction.

For more discussion and examples of item arrays, please read the Introduction page on Item Arrays.

Implemented types

• GraphObject

Implementers

• Part

Available extensions

• GraphObject$Typings
• Panel$Typings

Annotations

• @JS()
• @staticInterop

Constructors

Panel.$1()

factory

Panel.$2([dynamic init])

factory

Panel.$3([Object? type, dynamic init])

factory

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

auto ↔ PanelLayout

This value for #type resizes the main element to fit around the other elements; the main element is the first GraphObject with GraphObject#isPanelMain set to true, or else the first GraphObject if none have that property set to true.

getter/setter pair

graduated ↔ PanelLayout

This value for #type is used to draw regular tick marks and labels along some shape. The main element is the first GraphObject with GraphObject#isPanelMain set to true, or else the first GraphObject if none have that property set to true.

getter/setter pair

grid ↔ PanelLayout

This value for #type is used to draw regular patterns of lines.

getter/setter pair

horizontal ↔ PanelLayout

This value for #type lays out the elements horizontally with their GraphObject#alignment property dictating their alignment on the Y-axis.

getter/setter pair

link ↔ PanelLayout

This value for #type is used for Links and adornments that act as Links.

getter/setter pair

position ↔ PanelLayout

The default #type, arranges each element according to their GraphObject#position.

getter/setter pair

spot ↔ PanelLayout

This value for #type arranges GraphObjects about a main element using the GraphObject#alignment and GraphObject#alignmentFocus properties; the main element is the first GraphObject with GraphObject#isPanelMain set to true, or else the first GraphObject if none have that property set to true.

getter/setter pair

table ↔ PanelLayout

This value for #type arranges GraphObjects into rows and columns; set the GraphObject#row and GraphObject#column properties on each element.

getter/setter pair

tableColumn ↔ PanelLayout

Organizational Panel type that is only valid inside of a Table panel; This Panel ignores its angle and scale, and does not have a meaningful size on its own, it is only an organizational container for other elements of a Panel.

getter/setter pair

tableRow ↔ PanelLayout

Organizational Panel type that is only valid inside of a Table panel; This Panel ignores its angle and scale, and does not have a meaningful size on its own, it is only an organizational container for other elements of a Panel.

getter/setter pair

vertical ↔ PanelLayout

This value for #type lays out the elements vertically with their GraphObject#alignment property dictating their alignment on the X-axis.

getter/setter pair

viewbox ↔ PanelLayout

This value for #type rescales a single GraphObject to fit inside the panel depending on the panel's Panel#viewboxStretch property.

getter/setter pair

Static Methods

definePanelLayout(String layoutName, PanelLayout layout) → void

Register a PanelLayout. This is called when making new Panel types. See the PanelLayout sample for an example.