Constructs an empty Panel of the given type. 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. The string value such as "Auto" may also be used.
Usage example:
const p = new go.Panel("Auto", {
margin: 5,
background: "red"
});
Panel Type as either a string or PanelLayout. such as "Vertical", "Auto", or Panel.Vertical, Panel.Auto, are accepted. If not supplied, the default Panel type is "Position".
Optional initialization properties.
Constructs an empty Panel. Default type is Panel.Position.
Optional initialization properties.
For Panels which are elements of Spot Panels: Gets or sets the name of this Panel's element that should be used as the alignment object instead of this Panel.
This allows Spot Panels to align objects that are nested in the element tree of its own elements.
For Table Panels: This read-only property returns the number of columns. This value is only valid after the Panel has been measured.
For Table Panels: Gets or sets how this Panel's columns deal with extra space. Valid values are RowColumnDefinition.ProportionalExtra and RowColumnDefinition.None. The default is RowColumnDefinition.ProportionalExtra.
Gets or sets the optional model data to which this panel is data-bound. 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.
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. The default value is Spot.Default, which is interpreted by the Panel in whatever manner seems reasonable, depending on the Panel type.
For Table Panels: Gets or sets the default dash array for a column's separator. 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.
For Table Panels: Gets or sets the default stroke (color) for columns provided a given column has a nonzero RowColumnDefinition.separatorStrokeWidth. RowColumnDefinition.separatorDashArray can override this default value. The default value is null -- no line is drawn.
For Table Panels: Gets or sets the default stroke width for a column's separator. RowColumnDefinition.separatorStrokeWidth can override this default value. The default value is 1. Any new value must be a real, non-negative number.
For Table Panels: Gets or sets the default dash array for a row's separator. RowColumnDefinition.separatorDashArray 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.
For Table Panels: Gets or sets the default stroke (color) for rows provided a given row has a nonzero RowColumnDefinition.separatorStrokeWidth. RowColumnDefinition.separatorStroke can override this default value. The default value is null -- no line is drawn.
For Table Panels: Gets or sets the default stroke width for a row's separator. RowColumnDefinition.separatorStrokeWidth can override this default value. The default value is 1. Any new value must be a real, non-negative number.
For Table Panels: Gets or sets the additional padding for rows and columns. Padding is applied both before and after a row or column's contents.
Gets or sets the default stretch of this Panel, used as the stretch for an element when its GraphObject.stretch value is GraphObject.Default. The default value is GraphObject.Default, which typically resolves to GraphObject.None.
For Graduated Panels: Gets or sets the maximum value represented. Must be greater than graduatedMin. The default is 100.
For Graduated Panels: Gets or sets the minimum value represented. Must be less than graduatedMax. The default is 0.
For Graduated Panels: This read-only property returns the range of values represented by the Panel.
For example, a graduatedMin of 25 and graduatedMax of 75 would return 50.
For Graduated Panels: Gets or sets the base value which is marked with a tick. The default is 0.
For Graduated Panels: Gets or sets the difference between two consecutive values marked by ticks. Must be positive. The default is 10.
For Grid Panels: Gets or sets the distance between lines. The units are in local coordinates. The default is 10x10. Any new width or height must be a positive real number.
For Grid Panels: Gets or sets an origin point for the grid cells. The units are in local coordinates. The default is (0,0). Any new value must use real numbers.
For Spot Panels: Gets or sets whether this Panel's main element clips instead of fills. The main element will not paint its stroke, if it has any. This assumes that the main element is a Shape.
Since 2.2: For Groups: Gets or sets whether this Group's Placeholder clips its member nodes. For compatibility, if the Group is a Spot Panel, it will not clip its members.
When this property is true, the Spot panel will size itself to be the intersection of the main element bounds and
all other elements' bounds, rather than the union of these bounds.
Gets or sets whether this Panel or any GraphObject inside the panel actually responds to user click events. It may be used as a Binding target. See how this property is used in Buttons.js.
This property does not have any effect on picking ("hit-testing") -- that behavior is implemented by the GraphObject.pickable property. When this property is false, non-click events may still occur on this panel or on objects within this panel. This property is normally only used for Panels that are GraphObject.isActionable.
Call GraphObject.isEnabledObject to decide whether a particular object can be clicked.
For Horizontal and Vertical Panels: gets or sets whether this Panel arranges its contents from the typical side (left and top, respectively), or the opposite side (right and bottom, respectively).
The default value is false.
Gets or sets a JavaScript Array of values or objects, each of which will be represented by a Panel as elements in this Panel. 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. You may also reset this property to its current value (the modified Array) or call updateTargetBindings, if there is a Binding whose target is this property.
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.
Item Arrays should not be used with Grid Panels or Graduated Panels as they may not have nested Panels.
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'. 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.
Gets the index of this Panel's data if it was created to represent an item in its containing Panel's Panel.itemArray. 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.
Gets or sets the default Panel template used as the archetype for item data that are in itemArray.
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.
Gets or sets a Map mapping template names to Panels. 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.
For Table Panels: Gets or sets the first column that this Panel displays. The default value is 0.
Gets or sets the space between this Panel's border and its content. Unlike GraphObject.margin, padding expands the area inside of the Panel's border. If this Panel's size is unconstrained, this will increase the size of the panel. If this Panel's size is constrained, this will decrease the total area for the Panel elements to arrange themselves.
Unlike margin, increases in size due to padding are visually covered by the GraphObject.background.
Padding cannot contain negative numbers. The default value is a Margin of zero.
For Table Panels: This read-only property returns the number of rows. This value is only valid after the Panel has been measured.
For Table Panels: Gets or sets how this Panel's rows deal with extra space. Valid values are RowColumnDefinition.ProportionalExtra and RowColumnDefinition.None. The default is RowColumnDefinition.ProportionalExtra.
For Table Panels: Gets or sets the first row that this Panel displays. The default value is 0.
Gets or sets the type of the Panel, which controls how the Panel's elements are measured and arranged. The value must be an instance of PanelLayout. The only predefined 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.
For Viewbox Panels: Gets or sets how the panel will resize its content.
Possible values are GraphObject.Uniform and GraphObject.UniformToFill. The default is GraphObject.Uniform.
Adds a number of GraphObjects to the end of this Panel's list of elements, visually in front of all of the other elements.
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.
Any number of GraphObjects.
this Panel
Creates a deep copy of this Panel and returns it.
Make a deep copy of this Panel and allow it to be used as a template.
This makes copies of Bindings, unlike the regular copy() method.
Pass true as the argument in order to freeze the Bindings,
allowing it to operate efficiently as a template.
A false value (which is the default) allows further additions/modifications
of the bindings in the copied Panel.
whether to freeze the Bindings in the copy; default is false
Returns the GraphObject in this Panel's list of elements at the specified index.
For Table Panels: Returns the cell at a given x-coordinate in local coordinates, or -1 if there are no RowColumnDefinitions for this Table Panel or if the argument is negative. Call GraphObject.getLocalPoint to convert a Point in document coordinates into a Point in local coordinates.
a zero-based integer
Return the Panel that was made for a particular data object in this panel's itemArray. If this returns a Panel, its data property will be the argument data object, and its containing GraphObject.panel will be this panel.
must be an Object, not a string or a number or a boolean or a function
or null if not found
Return an immediate child element whose GraphObject.isPanelMain is true, or else just return the first child element.
this may return null if there are no child elements
Search the visual tree starting at this Panel for a GraphObject whose GraphObject.name is the given name.
This does not recurse into the elements inside a Panel that holds elements for an itemArray.
The name to search for, using a case-sensitive string comparison.
If no such named object can be found, this returns null.
For Table Panels: Returns the row at a given y-coordinate in local coordinates, or -1 if there are no RowColumnDefinitions for this Table Panel or if the argument is negative. Call GraphObject.getLocalPoint to convert a Point in document coordinates into a Point in local coordinates.
a zero-based integer
For Table Panels: Gets the RowColumnDefinition for a particular column. 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.
the non-negative zero-based integer column index.
For Table Panels: Gets the RowColumnDefinition for a particular row. 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.
the non-negative zero-based integer row index.
For Graduated Panels: Returns the point that corresponds with a value, in the panel's coordinates.
If the value provided is not within the graduatedMin and graduatedMax, it will be constrained to within those values.
If this Panel is not a Graduated Panel, this method returns Point(NaN, NaN).
a value between graduatedMin and graduatedMax
an optional Point that is modified and returned
For Graduated Panels: Returns the value that corresponds with the given Point. The Point must be in the panel's coordinates. The value returned will be in the Graduated Panel's range.
If this Panel is not a Graduated Panel, this method returns NaN.
a Point in the Graduated Panel's coordinates
Adds a GraphObject to the Panel's list of elements at the specified index.
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.
A GraphObject.
Create and add new GraphObjects corresponding to and bound to the data in the itemArray, after removing all existing elements from this Panel. 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.
Removes a GraphObject from this Panel's list of elements.
A GraphObject.
Removes an GraphObject from this Panel's list of elements at the specified index.
For Table Panels: Removes the RowColumnDefinition for a particular row.
If this Panel is not a Table Panel, this method does nothing.
the non-negative zero-based integer row index.
For Table Panels: Removes the RowColumnDefinition for a particular row.
If this Panel is not a Table Panel, this method does nothing.
the non-negative zero-based integer row index.
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.
It is better to call Model.setDataProperty to modify data properties, because that will both record changes for undo/redo and will update all bindings that may depend on that property.
This method does nothing if data is null.
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.
Register a PanelLayout. This is called when making new Panel types. See the PanelLayout sample for an example.
Panel name
instance of the 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.
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.
This value for type is used to draw regular patterns of lines.
This value for type lays out the elements horizontally with their GraphObject.alignment property dictating their alignment on the Y-axis.
The default type, arranges each element according to their GraphObject.position.
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.
This value for type arranges GraphObjects into rows and columns; set the GraphObject.row and GraphObject.column properties on each element.
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.
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.
This value for type lays out the elements vertically with their GraphObject.alignment property dictating their alignment on the X-axis.
This value for type rescales a single GraphObject to fit inside the panel depending on the panel's Panel.viewboxStretch property.
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. The second argument may also be an instance of PanelLayout, if you want to use a custom panel layout.
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.
Or to get a green bar effect:
But Grid Panels can also be stand alone objects:
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.
Only the main shape of a Graduated Panel participates in object picking, but a
backgroundcan 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.
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.