GraphObject class

This is the abstract base class for all graphical objects. Classes inheriting from GraphObject include: Shape, TextBlock, Picture, and Panel. From the Panel class the Part class is derived, from which the Node and Link classes derive.

It is very common to make use of the static function GraphObject.make in order to build up a visual tree of GraphObjects. You can see many examples of this throughout the Introduction, starting at Building Objects, and the Samples, starting with Minimal Sample.

Since GraphObject is an abstract class, programmers do not create GraphObjects themselves, but this class defines many properties used by all kinds of GraphObjects.

The only visual property on GraphObject is #background. However one can control whether the GraphObject is drawn at all by setting #visible, or by setting #opacity to zero if you still want the GraphObject to occupy space. Call the #isVisibleObject predicate to determine whether the object is visible and all of its containing panels are visible. Also, if you want to control whether any mouse or touch events "see" the GraphObject, you can set #pickable to false.

For more information about specifying how things get drawn, see the properties on the Shape, TextBlock, and Picture classes.

GraphObject Sizing

GraphObject defines most of the properties that cause objects to size themselves differently. The most prominent ones include:

• The #desiredSize, #minSize, and #maxSize properties are used to explicitly set or limit the size of visual elements. #width and #height are convenience properties that set the #desiredSize width and height, respectively.
• The #angle and #scale properties are used to transform visual elements.
• The #stretch property determines how a GraphObject will fill its visual space, contextually granted to it by its containing Panel. Top-level (Part) GraphObjects are not affected by this property because they are always granted infinite space.

All GraphObjects in a Diagram are measured and then arranged by their containing Panels in a tree-like fashion. After measuring and arranging, a GraphObject will have valid values for the read-only properties #naturalBounds, #measuredBounds, and #actualBounds.

• The #naturalBounds of a GraphObject describe its local size, without any transformations (#scale, #angle) affecting it.
• The #measuredBounds of a GraphObject describe its size within its containing Panel.
• The #actualBounds of a GraphObject describe its position and given size inside of its panel. This size may be smaller than #measuredBounds, for instance if a GraphObject with a large #desiredSize is placed in a Panel of a smaller #desiredSize. Smaller #actualBounds than #measuredBounds typically means an object will be cropped.

See the Introduction page on sizing for usage information and examples.

GraphObject Size and Position within Panel

Several GraphObject properties guide the containing Panel for how to size and position the object within the panel.

• The #alignment specifies where the object should be relative to some area of the panel. For example, an alignment value of Spot.BottomRight means that the GraphObject should be at the bottom-right corner of the panel.
• The #alignmentFocus specifies precisely which point of the GraphObject should be aligned at the #alignment spot.
• The #column and #row properties are only used by Panel.Table panels, to indicate where the GraphObject should be.
• The #columnSpan and #rowSpan properties tell the Panel.Table panel how large the GraphObject should be.
• The #isPanelMain property indicates to some kinds of Panels that the GraphObject is the "primary" object that other panel children should be measured with or positioned in.
• The #margin property tells the containing Panel how much extra space to put around this GraphObject.
• The #position property is used to determine the relative position of GraphObjects when they are elements of a Panel.Position panel.

See the Introduction page on Panels and Table Panels for an overview of the capabilities.

Top-level GraphObjects are Parts

A Part is a derived class of GraphObject representing a top-level object. All top-level GraphObjects must be Parts, and Node, Link, Group, and Adornment derive from Part. The position of a Part determines the point of the Part's top-left corner in document coordinates. See also Part#location, which supports an way to specify the position based on a different spot of a different element within the Part.

There are several read-only properties that help navigate up the visual tree.

• #panel returns the Panel that directly contains this GraphObject
• #part returns the Part that this GraphObject is in, perhaps via intervening Panels; this is frequently used in order to get to the model data, Panel#data
• #layer returns the Layer that this GraphObject's Part is in
• #diagram returns the Diagram that this GraphObject's Part's Layer is in

See the Visual Tree sample for a diagram displaying the visual tree of a simple diagram.

User Interaction

GraphObjects have several properties enabling dynamic customizable interaction. There are several definable functions that execute on input events: #mouseDragEnter, #mouseDragLeave, #mouseDrop, #mouseEnter, #mouseHold, #mouseHover, #mouseLeave, and #mouseOver. For example, you could define mouse enter-and-leave event handlers to modify the appearance of a link as the mouse passes over it:

myDiagram.linkTemplate =
  $(go.Link,
    $(go.Shape,
      { strokeWidth: 2, stroke: "gray" },  // default color is "gray"
      { // here E is the InputEvent and OBJ is this Shape
        mouseEnter: (e, obj) => { obj.strokeWidth = 4; obj.stroke = "dodgerblue"; },
        mouseLeave: (e, obj) => { obj.strokeWidth = 2; obj.stroke = "gray"; }
      }));

There are #click, #doubleClick, and #contextClick functions that execute when a user appropriately clicks the GraphObject. These click functions are called with the InputEvent as the first argument and this GraphObject as the second argument. For example, you could define a click event handler on a Node that goes to another page:

myDiagram.nodeTemplate =
  $(go.Node, "Auto",
    $(go.Shape, "RoundedRectangle",
      new go.Binding("fill", "color")),
    $(go.TextBlock,
      { name: "TB", margin: 3 },
      new go.Binding("text", "key")),
    { // second arg will be this GraphObject, which in this case is the Node itself:
      click: (e, node) => {
        window.open("https://en.wikipedia.org/Wiki/" + node.data.key);
      }
    });

Note: you may prefer defining DiagramEvent listeners on the Diagram rather than on individual GraphObjects. DiagramEvents also include more general events that do not necessarily correspond to input events.

The properties #actionCancel, #actionDown, #actionMove, and #actionUp define functions to execute when the GraphObject's #isActionable property is set to true (default false). See the ActionTool for more detail.

See the Introduction page on Events for a more general discussion.

GraphObjects as Ports

In GoJS, Links can only connect to elements within a Node that are specified as "ports", and by default the only port is the Node itself. Setting the #portId of a GraphObject inside a Node allows that object to act as a port. Note: the only kind of model that can save which port a link is connected with, i.e. portIds that are not an empty string, is a GraphLinksModel whose GraphLinksModel#linkFromPortIdProperty and GraphLinksModel#linkToPortIdProperty have been set to name properties on the link data objects.

GraphObjects have several properties that are only relevant when they are acting as ports. These port-related properties are:

• #portId, which must be set to a string that is unique within the Node, in order for this GraphObject to be treated as a "port", rather than the whole node
• #fromSpot and #toSpot, where a link should connect with this port
• #fromEndSegmentLength and #toEndSegmentLength, the length of the link segment adjacent to this port
• #fromShortLength and #toShortLength, the distance the link should terminate before touching this port
• #fromLinkable and #toLinkable, whether the user may draw links connecting with this port
• #fromLinkableDuplicates and #toLinkableDuplicates, whether the user may draw multiple links between the same pair of ports
• #fromLinkableSelfNode and #toLinkableSelfNode, whether the user may draw a link between ports on the same node
• #fromMaxLinks and #toMaxLinks, to limit the number of links connecting with this port in a particular direction

See the Introduction page on ports and link routing and link connection points for port usage information and examples.

GraphObjects as labels on a Link

GraphObjects can also be used as "labels" on a Link. In addition to the #alignmentFocus property, these properties direct a Link Panel to position a "label" at a particular point along the route of the link, in a particular manner:

• #segmentIndex, which segment the label should be on
• #segmentFraction, how far along the segment the label should be
• #segmentOffset, where the label should be positioned relative to the segment
• #segmentOrientation, how the label should be rotated relative to the angle of the segment

See the Introduction page on link labels for examples of how to make use of labels on Links.

Interactive Behavior

There are several properties that specify fairly high-level interactive behavior:

• #cursor, a CSS string specifying a cursor
• #contextMenu, an Adornment
• #toolTip, an Adornment

For more information, please read the Introduction page about Context Menus and the page about ToolTips.

Also see the Basic sample for examples of how to show context menus and tooltips.

Implementers

• Panel
• Picture
• Placeholder
• Shape
• TextBlock

Available Extensions

• GraphObject$Typings

Annotations

• @JS()
• @staticInterop

Constructors

GraphObject()

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

default$ ↔ EnumValue

GraphObjects with this enumeration as the value of GraphObject#stretch are stretched depending on the context they are used. For instance a 'Circle' figure might be uniformly stretched whereas an 'Ellipse' figure might be non-uniformly stretched.

getter/setter pair

fill ↔ EnumValue

GraphObjects with this enumeration as the value of GraphObject#stretch are scaled in both directions so as to fit exactly in the given bounds; there is no clipping but the aspect ratio may change, causing the object to appear stretched.

getter/setter pair

flipBoth ↔ EnumValue

GraphObjects with this enumeration as the value of Picture#flip or TextBlock#flip are drawn with both X and Y coordinates reversed.

getter/setter pair

flipHorizontal ↔ EnumValue

GraphObjects with this enumeration as the value of Picture#flip or TextBlock#flip are drawn mirror-image, with X coordinate points increasing towards the left.

getter/setter pair

flipVertical ↔ EnumValue

GraphObjects with this enumeration as the value of Picture#flip or TextBlock#flip are drawn upside-down, with Y coordinate points increasing upwards.

getter/setter pair

horizontal ↔ dynamic

GraphObjects with this enumeration as the value of GraphObject#stretch are scaled as much as possible in the x-axis. In another context, can be used as a value of PanelLayout, so type is "any".

getter/setter pair

make → ({T Function<T extends Adornment>(Make cls, [Iterable? initializers]) $1, T Function<T extends Panel>(MakeOptions cls, [Iterable? initializers]) $2, T Function<T extends GraphObject>(String cls, [Iterable? initializers]) $3, dynamic Function<CT extends ConstructorType<CT>>(CT cls, [Iterable? initializers]) $4})

Overload accessor: $1, $2, $3, $4

no setter

none ↔ EnumValue

GraphObjects with this enumeration as the value of GraphObject#stretch are not automatically scaled to fit in the given bounds; there may be clipping in one or both directions if the available dimensions are too small.

getter/setter pair

uniform ↔ EnumValue

Pictures with this enumeration as the value of Picture#imageStretch are drawn with equal scale in both directions to fit the larger side of the image bounds; Panels of type Viewbox with this as the value of Panel#viewboxStretch scale the contained element equally in both directions to fit the larger side of the element's bounds in the given bounds.

getter/setter pair

uniformToFill ↔ EnumValue

Pictures with this enumeration as the value of Picture#imageStretch are drawn with equal scale in both directions to fit the arranged (actual) bounds; Panels of type Viewbox with this as the value of Panel#viewboxStretch scale the contained element equally in both directions to fit the smaller side of the element's bounds in the given bounds. There may be clipping in one dimension.

getter/setter pair

vertical ↔ dynamic

GraphObjects with this enumeration as the value of GraphObject#stretch are scaled as much as possible in the y-axis. In another context, can be used as a value of PanelLayout, so type is "any".

getter/setter pair

Static Methods

build<T extends GraphObject>(String name, [dynamic config, Iterable? args]) → T

This static function creates an instance that was defined with GraphObject.defineBuilder. Once this is called one can use the name as the first argument for GraphObject.make. Names are case sensitive.

defineBuilder(String name, Object func(Array)) → void

This static function defines a named function that GraphObject.make or GraphObject.build can use to build objects. Once this is called one can use the name as the first argument for GraphObject.make or GraphObject.build. Names are case sensitive.

takeBuilderArgument(Array args, [dynamic defval, bool pred([dynamic])?]) → dynamic

This static function returns the first argument from the arguments array passed to a GraphObject.defineBuilder function by GraphObject.make. By default this requires the first argument to be a string, but you can provide a predicate to determine whether the argument is suitable.