Class Panel

Extends GraphObject. 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:

Using GraphObject.make, the second argument can be used to declare the Panel type:
// Either:
$(go.Panel, go.Panel.Horizontal, ...
// Or:
$(go.Panel, "Horizontal", ...

// Full example:
$(go.Panel, "Horizontal",
  { width: 60, height: 60 }, // panel properties
  // elements in the panel:
  $(go.Shape, "Rectangle", { stroke: "lime" }),
  $(go.TextBlock, "Some Text")
) // end of panel definition 

For an overview of all Panel types, please read the Introduction page on Panels and Table 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.

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

$(go.Diagram, "myDiagramDiv",
  { . . .
    grid: $(go.Panel, "Grid",
            { gridCellSize: new go.Size(40, 40) },
            $(go.Shape, "LineH", { stroke: "lightgray" }),
            $(go.Shape, "LineV", { stroke: "lightgray" })
          ),
    . . .
  });
Or to get a green bar effect:
$(go.Diagram, "myDiagramDiv",
  { . . .
    grid: $(go.Panel, "Grid",
            { gridCellSize: new go.Size(100, 100) },
            $(go.Shape, "BarH", { fill: "lightgreen", height: 50 })
          ),
    . . .
  });
But Grid Panels can also be stand alone objects:
$(go.Node, go.Panel.Grid,
  { gridCellSize: new go.Size(6, 6), width: 60, height: 60 },
  $(go.Shape, "LineH", { stroke: "gray" }),
  $(go.Shape, "LineV", { stroke: "gray" }))

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

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.

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 or GraphObject.areaBackground is specified or separators are specified either as defaults for the whole Table Panel or on individual RowColumnDefinitions.

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.

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.

Constructor Summary Details

Name Description
Panel(type)

Constructs an empty Panel of the given type.More... Default type is Panel.Position. The panel type must be one of the enumerated values defined on the Panel class, including: Panel.Position, Panel.Vertical, Panel.Horizontal, Panel.Table, Panel.Auto, Panel.Spot, or Panel.Viewbox.

Parameters:
{EnumValue=} type
If not supplied, the default Panel type is Panel.Position.

Properties Summary Details

Name, Value Type Description
columnCount
{number}

This read-only property returns the number of columns in this Panel if it is of type Panel.Table.More... This value is only valid after the Panel has been measured.

columnSizing
{EnumValue}

Gets or sets how this Panel's columns deal with extra space if the Panel is of type Panel.Table.More... Valid values are RowColumnDefinition.ProportionalExtra and RowColumnDefinition.None. The default is RowColumnDefinition.ProportionalExtra.

data
{Object}

Gets or sets the optional model data to which this panel is data-bound.More... The data must be a JavaScript Object if this is a Part. The data can be any JavaScript value if this is a Panel created for an item in an Array that was data-bound by the itemArray property. The default value is null.

Setting it to a new value automatically calls updateTargetBindings in order to assign new values to all of the data-bound GraphObject properties.

Once you set this property you cannot add, remove, or modify any data bindings on any of the GraphObjects in the visual tree of this Panel, including on this panel itself.

You should not modify this property on a Part that is created automatically to represent model data, nor on a Panel that is created automatically for a data item in the containing Panel's Panel.itemArray. Call Model.removeNodeData and Model.addNodeData if you want to replace this Part with another one, or call Model.removeArrayItem and Model.insertArrayItem if you want to replace this Panel with another one.

Although you might not be able to replace this data value if this Part was created automatically by the Diagram, you can still modify that data object's properties. Call the appropriate Model method for changing properties that affect the structure of the diagram. Call Model.setDataProperty for changing other properties that may be the sources of Bindings on GraphObject properties that are in the visual tree of this panel/part.

defaultAlignment
{Spot}

Gets or sets the default alignment spot of this Panel, used as the alignment for an element when its GraphObject.alignment value is Spot.Default.More... The default value is Spot.Default, which is interpreted by the Panel in whatever manner seems reasonable, depending on the Panel type.

defaultColumnSeparatorDashArray
{Array.} 1.2

Gets or sets the default dash array for a column's separator in a Table Panel.More... RowColumnDefinition.separatorStrokeWidth can override this default value.

Must be an array of positive numbers and zeroes, or else null to indicate a solid line.

For example, the array [5, 10] would create dashes of 5 pixels and spaces of 10 pixels.

Setting an array with all zeroes will set the value to null.

Default is null.

defaultColumnSeparatorStroke
{string|Brush} 1.2

Gets or sets the default stroke (color) for columns in a Table Panel provided a given column has a nonzero RowColumnDefinition.separatorStrokeWidth.More... RowColumnDefinition.separatorStroke can override this default value. The default value is null -- no line is drawn.

defaultColumnSeparatorStrokeWidth
{number} 1.2

Gets or sets the default stroke width for a column's separator in a Table Panel.More... RowColumnDefinition.separatorStrokeWidth can override this default value. The default value is 1. Any new value must be a real, non-negative number.

defaultRowSeparatorDashArray
{Array.} 1.2

Gets or sets the default dash array for a row's separator in a Table Panel.More... RowColumnDefinition.separatorStrokeWidth can override this default value.

Must be an array of positive numbers and zeroes, or else null to indicate a solid line.

For example, the array [5, 10] would create dashes of 5 pixels and spaces of 10 pixels.

Setting an array with all zeroes will set the value to null.

Default is null.

defaultRowSeparatorStroke
{string|Brush} 1.2

Gets or sets the default stroke (color) for rows in a Table Panel provided a given row has a nonzero RowColumnDefinition.separatorStrokeWidth.More... RowColumnDefinition.separatorStroke can override this default value. The default value is null -- no line is drawn.

defaultRowSeparatorStrokeWidth
{number} 1.2

Gets or sets the default stroke width for a row's separator in a Table Panel.More... RowColumnDefinition.separatorStrokeWidth can override this default value. The default value is 1. Any new value must be a real, non-negative number.

defaultSeparatorPadding
{Margin} 1.2

Gets or sets the additional padding for rows and columns in a Table Panel.More... Padding is applied both before and after a row or column's contents.

defaultStretch
{EnumValue}

Gets or sets the default stretch of this Panel, used as the stretch for an element when its GraphObject.stretch value is GraphObject.Default.More... The default value is GraphObject.Default, which typically resolves to GraphObject.None.

elements
{Iterator.}

This read-only property returns an iterator over the collection of the GraphObjects that this panel manages.More...

You can change the collection by calling add, insertAt, remove, or removeAt.

You can also get direct access to individual elements by calling elt.

gridCellSize
{Size}

Gets or sets the distance between lines in a Grid panel.More... The units are in local coordinates. The default is 10x10. Any new width or height must be a positive real number.

gridOrigin
{Point}

Gets or sets an origin point for the grid cells in a Grid panel.More... The units are in local coordinates. The default is (0,0). Any new value must use real numbers.

itemArray
{Array}

Gets or sets a JavaScript Array of values or objects, each of which will be represented by a Panel as elements in this Panel.More... Replacing this array results all of this panel's child objects being replaced with a copy of the Panel found in itemTemplateMap for each particular item in the Array.

Because the software does not receive any notifications when an Array is modified, any insertions or removals or replacements of data in the Array will not be noticed unless you call Model.insertArrayItem or Model.removeArrayItem.

When binding this 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 and perhaps a GraphLinksModel.copyLinkDataFunction.

Any JavaScript Object that is in this Array must only appear once in the array and must not appear in any other Panel.itemArrays. Use findItemPanelForData to find the data-bound Panel created for an Object in this panel's item Array.

Non-Object values in an item Array may appear multiple times. An item Array may be shared by multiple Panels.

itemCategoryProperty
{string|function(*):string}

Gets or sets the name of the item data property that returns a string describing that data's category, or a function that takes an item data object and returns that string; the default value is the name 'category'.More... This is used to distinguish between different kinds of items in the itemArray.

The name must not be null. If the value is an empty string, the category is assumed to be an empty string, the default category name, for all item data objects. You must not change this property when the itemArray already has a value.

itemIndex
{number} 1.4

Gets the index of this Panel's data if it was created to represent an item in its containing Panel's Panel.itemArray.More... The default value is NaN.

This is only set internally by code such as rebuildItemElements or Model.insertArrayItem when building or shifting Panel representing items in the Panel whose Panel.itemArray was set or bound to an Array of value.

This property can be used in data bindings within the item template to produce values that depend on its position in the item Array. For example:

 $(go.Panel, // the item Panel
   . . .,
   new go.Binding("itemArray", "someProperty"),
   {
     itemTemplate:
       $(go.Panel,
         // set Panel.background to a color based on the Panel.itemIndex
         new go.Binding("background", "itemIndex",
                        // using this conversion function
                        function(i) { return (i%2 === 0) ? "lightgreen" : "lightyellow"; })
                  // bound to this Panel itself, not to the Panel.data item
                  .ofObject(),
         $(go.TextBlock,  // a trivial item template, just showing some text
           new go.Binding("text"))  // sets TextBlock.text = data.text
       )
   }
 )

The main element of a Spot or Auto or Link Panel, or the first TableRow or TableColumn element of a Table Panel whose isPanelMain property is true, will not have this property set to a number, because it will not have been created by rebuildItemElements.

itemTemplate
{Panel}

Gets or sets the default Panel template used as the archetype for item data that are in itemArray.More...

Setting this property just modifies the itemTemplateMap by replacing the entry named with the empty string. Any new value must be a Panel but not a Part. By default this property is null.

GraphObject.copy when copying a panel will share the itemTemplateMap between the original panel and the copied panel.

itemTemplateMap
{Map.}

Gets or sets a Map mapping template names to Panels.More... One of these Panels is copied for each item data that is in the itemArray. Replacing this map will automatically rebuild all of the elements in this Panel.

By default this property is null. All values in the Map must be Panels but not Parts.

If you modify this Map, by replacing a Panel or by adding or removing a map entry, you need to explicitly call rebuildItemElements afterwards.

GraphObject.copy when copying a panel will share the itemTemplateMap between the original panel and the copied panel.

leftIndex
{number}

Gets or sets the first column that this Panel of type Panel.Table displays.More... The default value is 0.

See also:
padding
{Margin|number}

Gets or sets the space between this Panel's border and its content, depending on the type of panel.More... Unlike GraphObject.margin, padding expands the area inside of the Panel's border.

Padding cannot contain negative numbers. The default value is a Margin of zero.

rowCount
{number}

This read-only property returns the number of rows in this Panel if it is of type Panel.Table.More... This value is only valid after the Panel has been measured.

rowSizing
{EnumValue}

Gets or sets how this Panel's rows deal with extra space if the Panel is of type Panel.Table.More... Valid values are RowColumnDefinition.ProportionalExtra and RowColumnDefinition.None. The default is RowColumnDefinition.ProportionalExtra.

topIndex
{number}

Gets or sets the first row that this Panel of type Panel.Table displays.More... The default value is 0.

See also:
type
{EnumValue}

Gets or sets the type of the Panel, which controls how the Panel's elements are measured and arranged.More... The only accepted values are listed as constant properties of Panel, including:

The default value is Panel.Position.

You must not modify this property once the Panel has been measured or the Panel has been added to another Panel.

viewboxStretch
{EnumValue}

Gets or sets how a Viewbox panel will resize its content.More...

Possible values are GraphObject.Uniform and GraphObject.UniformToFill. The default is GraphObject.Uniform.

Properties borrowed from class GraphObject:
actionCancel, actionDown, actionMove, actionUp, actualBounds, alignment, alignmentFocus, angle, areaBackground, background, click, column, columnSpan, contextClick, contextMenu, cursor, Default, desiredSize, diagram, doubleClick, Fill, fromEndSegmentDirection, fromEndSegmentLength, fromLinkable, fromLinkableDuplicates, fromLinkableSelfNode, fromMaxLinks, fromShortLength, fromSpot, height, isActionable, isPanelMain, layer, margin, maxSize, measuredBounds, minSize, mouseDragEnter, mouseDragLeave, mouseDrop, mouseEnter, mouseHold, mouseHover, mouseLeave, mouseOver, name, naturalBounds, None, opacity, panel, part, pickable, portId, position, row, rowSpan, scale, segmentFraction, segmentIndex, segmentOffset, segmentOrientation, shadowVisible, stretch, toEndSegmentDirection, toEndSegmentLength, toLinkable, toLinkableDuplicates, toLinkableSelfNode, toMaxLinks, toolTip, toShortLength, toSpot, Uniform, UniformToFill, visible, width

Method Summary Details

Name, Return Type Description
add(element)

Adds a GraphObject to the end of this Panel's list of elements, visually in front of all of the other elements.More...

If the element to be added is already in this Panel's list of elements, the object is moved to the end of the list. You cannot add a GraphObject to a Panel if that GraphObject is already in a different Panel.

Parameters:
{GraphObject} element
A GraphObject.
copy()
{Panel}

Creates a deep copy of this Panel and returns it.

Returns:
{Panel}
elt(idx)

Returns the GraphObject in this Panel's list of elements at the specified index.More...

Parameters:
{number} idx
Returns:
{GraphObject}
findColumnForLocalX(x)
{number} 1.2

Returns the cell at a given x-coordinate in local coordinates.More... Call GraphObject.getLocalPoint to convert a Point in document coordinates into a Point in local coordinates.

If this Panel is not a Table Panel, this method returns -1.

See also:
Parameters:
{number} x
Returns:
{number} a zero-based integer
findItemPanelForData(data)
{Panel} 1.6

Return the Panel that was made for a particular data object in this panel's itemArray.More... If this returns a Panel, its data property will be the argument data object, and its containing GraphObject.panel will be this panel.

Parameters:
data
must be an Object, not a string or a number or a boolean or a function
Returns:
{Panel} or null if not found
findMainElement()
{GraphObject} 1.5

Return an immediate child element whose GraphObject.isPanelMain is true, or else just return the first child element.

Returns:
{GraphObject} this may return null if there are no child elements
findObject(name)

Search the visual tree starting at this Panel for a GraphObject whose GraphObject.name is the given name.More...

This does not recurse into the elements inside a Panel that holds elements for an itemArray.

Parameters:
{string} name
The name to search for, using a case-sensitive string comparison.
Returns:
{GraphObject} If no such named object can be found, this returns null.
findRowForLocalY(y)
{number} 1.2

Returns the row at a given y-coordinate in local coordinates.More... Call GraphObject.getLocalPoint to convert a Point in document coordinates into a Point in local coordinates.

If this Panel is not a Table Panel, this method returns -1.

Parameters:
{number} y
Returns:
{number} a zero-based integer
getColumnDefinition(idx)

Gets the RowColumnDefinition for a particular column in this Table Panel.More... If you ask for the definition of a column at or beyond the columnCount, it will automatically create one and return it.

If this Panel is not a Table Panel, this method returns null.

Parameters:
{number} idx
the non-negative zero-based integer column index.
Returns:
{RowColumnDefinition}
getRowDefinition(idx)

Gets the RowColumnDefinition for a particular row in this Table Panel.More... If you ask for the definition of a row at or beyond the rowCount, it will automatically create one and return it.

If this Panel is not a Table Panel, this method returns null.

Parameters:
{number} idx
the non-negative zero-based integer row index.
Returns:
{RowColumnDefinition}
insertAt(index, element)

Adds a GraphObject to the Panel's list of elements at the specified index.More...

If the element to be added is already in this Panel's list of elements, the object is moved to the specified index. You cannot add a GraphObject to a Panel that if that GraphObject is already in a different Panel.

Parameters:
{number} index
{GraphObject} element
A GraphObject.
rebuildItemElements()

Create and add new GraphObjects corresponding to and bound to the data in the itemArray, after removing all existing elements from this Panel.More... This method is automatically called when replacing the itemArray value, or when changing the value of itemTemplate or itemTemplateMap.

This uses itemCategoryProperty to determine the category for an item data. That string is used to look up a template in itemTemplateMap. The resulting template (which is also a Panel) is copied, added to this panel, and its itemIndex is set to its index in that Array. That new child Panel is then data-bound to that Array item by setting its data.

If itemArray is null, this method just removes all elements from this panel. Actually, if this Panel type is "Spot", "Auto", or "Link", the very first element is always kept by this method. Also, if this Panel type is "Table", and if the first element is a "TableRow" or "TableColumn" Panel whose isPanelMain property is set to true, that first element will be kept too. That is useful for defining literal TableRow headers in Table panels, when the header information is not kept as the first item in the itemArray.

It is wasteful to call this method after making some model data changes. It is better to call Model.setDataProperty, Model.addArrayItem, Model.insertArrayItem, or Model.removeArrayItem, or other model methods. Not only do those methods update efficiently, they also preserve unbound state and support undo/redo.

remove(element)

Removes a GraphObject from this Panel's list of elements.More...

Parameters:
{GraphObject} element
A GraphObject.
removeAt(idx)

Removes an GraphObject from this Panel's list of elements at the specified index.More...

Parameters:
{number} idx
removeColumnDefinition(idx)

Removes the RowColumnDefinition for a particular row in this Table Panel.More...

If this Panel is not a Table Panel, this method does nothing.

Parameters:
{number} idx
the non-negative zero-based integer row index.
removeRowDefinition(idx)

Removes the RowColumnDefinition for a particular row in this Table Panel.More...

If this Panel is not a Table Panel, this method does nothing.

Parameters:
{number} idx
the non-negative zero-based integer row index.
updateTargetBindings(srcprop)

Re-evaluate all data bindings on this panel, in order to assign new property values to the GraphObjects in this visual tree based on this object's data property values.More...

This method does nothing if data is null. This method also will not detect changes in JavaScript Arrays -- you may need to replace the itemArray with a new Array, or else call Model.insertArrayItem or Model.removeArrayItem.

Parameters:
{string=} srcprop
An optional source data property name: when provided, only evaluates those Bindings that use that particular property; when not provided or when it is the empty string, all bindings are evaluated.
Methods borrowed from class GraphObject:
bind, getDocumentAngle, getDocumentPoint, getDocumentScale, getLocalPoint, isContainedBy, isVisibleObject, setProperties

Constants Summary Details

Name Description
Auto {EnumValue}

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.

Grid {EnumValue}

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

Horizontal {EnumValue}

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

Position {EnumValue}

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

Spot {EnumValue}

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.

Table {EnumValue}

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

TableColumn 1.1 {EnumValue}

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.

TableRow 1.1 {EnumValue}

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.

Vertical {EnumValue}

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

Viewbox {EnumValue}

This value for type rescales a single GraphObject to fit inside the panel depending on the element's GraphObject.stretch property.