Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Panel

Hierarchy

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.

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

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.

Index

Inherited Members

Properties

Methods

Constructors

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.

    since

    1.7

  • For Table Panels: This read-only property returns the number of columns. This value is only valid after the Panel has been measured.

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

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

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

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

  • For Graduated Panels: Gets or sets the maximum value represented. Must be greater than graduatedMin. The default is 100.

    since

    1.7

  • For Graduated Panels: Gets or sets the minimum value represented. Must be less than graduatedMax. The default is 0.

    since

    1.7

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

    since

    1.7

  • For Graduated Panels: Gets or sets the base value which is marked with a tick. The default is 0.

    since

    1.7

  • For Graduated Panels: Gets or sets the difference between two consecutive values marked by ticks. Must be positive. The default is 10.

    since

    1.7

  • 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 Part.resizeObject 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.

    since

    1.7

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

    since

    1.7

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

    since

    1.4

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

    see

    topIndex

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

    see

    GraphObject.margin

  • 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 the first row that this Panel displays. The default value is 0.

    see

    leftIndex

Methods

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

    Parameters

    • Rest ...elements: GraphObject[]

      Any number of GraphObjects.

    Returns Panel

    this Panel

  • For Table Panels: Sets the column RowColumnDefinition given by the index. If the column definition does not exist on the Panel, this will create it. If it already exists on the Panel, this will copy the properties of the given RowColumnDefinition options onto that definition.

    This is a convenience method for addRowColumnDefinition. Instead of writing:

    .addRowColumnDefinition(new go.RowColumnDefinition({ column: 2, width: 60 }))
    

    You can write:

    .addColumnDefinition(2, { width: 60 })
    
    since

    2.3

    see

    addRowDefinition, addRowColumnDefinition

    Parameters

    • colIndex: number

      the non-negative zero-based integer column index.

    • options: Partial<RowColumnDefinition>

      the initialization options passed to the RowColumnDefinition constructor.

    Returns Panel

    this Panel

  • For Table Panels: Sets the given RowColumnDefinition. If the row or column definition does not exist on the Panel, this will create it. If it already exists on the Panel, this will copy the properties of the given RowColumnDefinition onto that RowColumnDefinition.

    since

    2.3

    see

    addRowDefinition, addColumnDefinition

    Parameters

    Returns Panel

    this Panel

  • For Table Panels: Sets the row RowColumnDefinition given by the index. If the row definition does not exist on the Panel, this will create it. If it already exists on the Panel, this will copy the properties of the given RowColumnDefinition options onto that definition.

    This is a convenience method for addRowColumnDefinition. Instead of writing:

    .addRowColumnDefinition(new go.RowColumnDefinition({ row: 2, height: 60 }))
    

    You can write:

    .addRowDefinition(2, { height: 60 })
    
    since

    2.3

    see

    addColumnDefinition, addRowColumnDefinition

    Parameters

    • rowIndex: number

      the non-negative zero-based integer row index.

    • options: Partial<RowColumnDefinition>

      the initialization options passed to the RowColumnDefinition constructor.

    Returns Panel

    this Panel

  • Creates a deep copy of this Panel and returns it.

    Returns Panel

  • copyTemplate(freeze?: boolean): Panel
  • 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.

    since

    2.2

    Parameters

    • Optional freeze: boolean

      whether to freeze the Bindings in the copy; default is false

    Returns Panel

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

    Parameters

    • idx: number

    Returns GraphObject

  • findColumnForLocalX(x: number): number
  • 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.

    see

    findRowForLocalY

    since

    1.2

    Parameters

    • x: number

    Returns number

    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.

    since

    1.6

    Parameters

    • data: ObjectData

      must be an Object, not a string or a number or a boolean or a function

    Returns Panel

    or null if not found

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

    since

    1.5

    Returns GraphObject

    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.

    Parameters

    • name: string

      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): number
  • 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.

    see

    findColumnForLocalX

    since

    1.2

    Parameters

    • y: number

    Returns number

    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.

    Parameters

    • idx: number

      the non-negative zero-based integer column index.

    Returns RowColumnDefinition

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

    Parameters

    • idx: number

      the non-negative zero-based integer row index.

    Returns RowColumnDefinition

  • graduatedPointForValue(val: number, result?: Point): Point
  • 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).

    see

    graduatedValueForPoint

    since

    1.7

    Parameters

    Returns Point

  • graduatedValueForPoint(pt: Point): number
  • 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.

    see

    graduatedPointForValue

    since

    1.7

    Parameters

    • pt: Point

      a Point in the Graduated Panel's coordinates

    Returns number

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

    Parameters

    Returns void

  • rebuildItemElements(): void
  • 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.

    Returns void

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

    Parameters

    Returns void

  • removeAt(idx: number): void
  • Removes an GraphObject from this Panel's list of elements at the specified index.

    Parameters

    • idx: number

    Returns void

  • removeColumnDefinition(idx: number): void
  • For Table Panels: Removes the RowColumnDefinition for a particular row.

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

    Parameters

    • idx: number

      the non-negative zero-based integer row index.

    Returns void

  • removeRowDefinition(idx: number): void
  • For Table Panels: Removes the RowColumnDefinition for a particular row.

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

    Parameters

    • idx: number

      the non-negative zero-based integer row index.

    Returns void

  • updateTargetBindings(srcprop?: string): void
  • 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.

    see

    Model.updateTargetBindings

    Parameters

    • Optional srcprop: string

      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.

    Returns void

  • definePanelLayout(layoutName: string, layout: PanelLayout): void
  • Register a PanelLayout. This is called when making new Panel types. See the PanelLayout sample for an example.

    since

    2.0

    Parameters

    • layoutName: string

      Panel name

    • layout: PanelLayout

      instance of the PanelLayout

    Returns void

Constants

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

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

    since

    1.7

    Returns PanelLayout

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

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

    since

    1.1

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

    since

    1.1

    Returns PanelLayout