GoJS® Shape Class

Class Shape

Extends GraphObject. A Shape is a GraphObject that shows a geometric figure. The Geometry determines what is drawn; the properties fill and stroke (and other stroke properties) determine how it is drawn.

There are generally two types of shapes: Those that use a custom Geometry by setting Shape.geometry, and those that receive an automatically generated Geometry using the value of figure, toArrow, or fromArrow. An explicitly set Geometry always supersedes the figure and arrowhead properties.

Some created Shapes:

var $ = go.GraphObject.make;  // for conciseness in defining GraphObjects

// A shape with the figure set to RoundedRectangle:
$(go.Shape, { figure: "RoundedRectangle", fill: "lightgreen" })
// Alternatively:
$(go.Shape, "RoundedRectangle", { fill: "lightgreen" })

// A shape with a custom geometry, using geometryString:
$(go.Shape,
    { geometry: go.Geometry.parse("M120 0 L80 80 0 50z") })

// A shape with a custom geometry, using geometryString:
$(go.Shape,
   { geometryString: "F M120 0 L80 80 0 50z",
     fill: "lightgreen" })

// A common link template, using two shapes,
// the first for the link path and the second for the arrowhead
myDiagram.linkTemplate =
  $(go.Link,
    // The first shape in a link is special, its geometry is set by the Link's routing,
    // so it does not need a geometry or figure set manually
    $(go.Shape,
      { strokeWidth: 2, stroke: 'gray' }),
    $(go.Shape,
      { toArrow: "Standard", fill: 'gray', stroke: null })
  );

You can see more custom geometry examples and read about geometryString on the Geometry Path Strings Introduction page.

When automatically generating a Shape Geometry, the value of toArrow takes precedence, then fromArrow, then figure. If the value of toArrow or fromArrow is "None" then it is ignored, and the "None" value of figure is identical to "Rectangle".

All of the predefined figures are shown in the Shapes sample. You can define your own named figures by calling the static function Shape.defineFigureGenerator. Get a Map of named figures by calling the static function Shape.getFigureGenerators.

All of the predefined arrowheads are shown in the Arrowheads sample. You can define your own named arrowheads by calling the static function Shape.defineArrowheadGeometry. Get a Map of named arrowheads by calling the static function Shape.getArrowheadGeometries.

You can see a copy of all of the built-in arrowhead definitions in this file: Arrowheads.js.

The Shape properties parameter1, and parameter2 determine details of the construction of some figure geometries. Specifically, they often set the spot1, spot2 for the Shape. These spots determine the "inner area" of an Auto panel when a Shape is the main object. See the Auto Panels section of the Panels Introduction page for more details.

Shapes use their geometric bounds when determining hit testing, but use rectangular bounds when participating in (panel) layouts.

Constructor Summary Details

Name	Description
Shape()	A newly constructed Shape has a default figure of "None", which constructs a rectangular geometry, and is filled and stroked with a black brush.

Properties Summary Details

Name, Value Type	Description
figure {string}	Gets or sets the figure name, used to construct a Geometry.More... The value must be a string. The default value is "None". The name can be any case but will always be canonicalized when set. For instance, setting "roundedrectangle" will set the value of figure to "RoundedRectangle". All of the predefined figures are shown in the Shapes sample. At most one of the following three properties may be set to a non-"None" value at the same time on the same shape: figure, toArrow, fromArrow. You can define your own named figures by calling the static function Shape.defineFigureGenerator.
fill {string\|Brush}	Gets or sets the Brush or string that describes how the geometry is filled when drawn.More... The default value is "black", causing the shape to be filled with solid black. Any valid CSS string can specify a solid color, and the Brush class can be used to specify a gradient or pattern. A null fill will mean no fill is drawn and the filled portion of the Shape will not be pickable. A "transparent" fill is useful when wanting to allow a shape to be pickable without obscuring any other objects behind it. More information about the syntax of CSS color strings is available at: CSS colors (mozilla.org). The geometry is filled before the stroke is drawn.
fromArrow {string}	Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link.More... Value must be a string. The default is "None", which means that this Shape is not an arrowhead, causing it to be the default Shape, a large filled Rectangle. If you want to have an arrowhead Shape but sometimes not show an arrowhead, you can set or bind the GraphObject.visible property, or you can set or bind this "toArrow" property to be the empty string. The arrowhead named "", an empty string, will display as nothing. The name can be any case but will always be canonicalized when set. For instance, setting "opentriangle" will set the value of the arrowhead to "OpenTriangle". All of the predefined arrowheads are shown in the Arrowheads sample. Setting this property may also set the GraphObject.segmentIndex, GraphObject.segmentOrientation, and GraphObject.alignmentFocus properties. This shape should be an element of a Link. At most one of the following three properties may be set to a non-"None" value at the same time on the same shape: figure, toArrow, fromArrow. You can define your own named arrowheads by calling the static function Shape.defineArrowheadGeometry. You can see a copy of all of the built-in arrowhead definitions in this file: Arrowheads.js.
geometry {Geometry}	Gets or sets the Shape's Geometry that defines the Shape's figure.More... Setting a geometry is not necessary if a figure is specified, as that will construct a geometry instead. Setting this geometry property will freeze the supplied Geometry. Setting this geometry property always overrides any set figure. The default value is null. See also: geometryString
geometryStretch {EnumValue}	Gets or sets how the shape's geometry is proportionally created given its computed size.More... Possible values are GraphObject.None, GraphObject.Fill, GraphObject.Uniform, and GraphObject.Default. The default is GraphObject.Default, which resolves to GraphObject.Fill for most figures, though some regular figures such as "Circle" and "Square" default to GraphObject.Uniform.
geometryString {string} 1.1	When set, creates a Geometry and normalizes it from a given path string, then sets the geometry property on this Shape and set the GraphObject.position to the amount computed by normalization.More... The property getter simply returns the toString value of the geometry, or the empty string if there is no Geometry value. See the Geometry Path Strings Introduction page for examples.
graduatedEnd {number} 1.7	Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this kind of tick should end.More... The default is 1. Any new value should range from 0 to 1.
graduatedStart {number} 1.7	Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this kind of tick should start.More... The default is 0. Any new value should range from 0 to 1.
interval {number}	Gets or sets how frequently this shape should be drawn within a "Grid" or "Graduated" Panel, in multiples of the Panel.gridCellSize or Panel.graduatedTickUnit.More... The default is 1. Any new value must be a positive integer.
isGeometryPositioned {boolean} 1.1	Gets or sets the whether the GraphObject.position of this shape denotes the top-left corner of this shape in panel coordinates or the origin of this geometry's coordinate system.More... Basically, this determines whether the strokeWidth affects the rendered location. A true value allows multiple shapes to be positioned precisely in a "Position" Panel independent of the stroke width. The default is false.
naturalBounds {Rect}	This read-only property returns the natural bounds of this Shape as determined by its geometry's bounds.More... The bounds will always include the (0,0) point. If there is no geometry available, it returns a Rect with the desiredSize, which may have NaN values for the width and height.
parameter1 {number}	Gets or sets a property for parameterizing the construction of a Geometry from a figure.More... The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.
parameter2 {number}	Gets or sets a property for parameterizing the construction of a Geometry from a figure.More... The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.
pathPattern {GraphObject} 1.6	Gets or sets a GraphObject that is drawn repeatedly along the path of the stroke of this shape.More... This property may be set to a shared GraphObject; the GraphObject should not belong to any Panel. Note that data bindings do not work in such shared GraphObjects, because they are not part of the visual tree. The default value is null, causing no object to be drawn repeatedly. Typically the object is a small Shape or a Picture. The larger the object is the worse the results will be, especially if the stroke has short segments or sharp curves. The stroke is always drawn normally -- having a value for this property will draw the value along the stroke as well, so it is commonplace to set the stroke to "transparent" and the strokeWidth to be as wide as the height of the GraphObject being drawn along the stroke. Examples of path patterns can be seen in the Relationships sample.
spot1 {Spot}	Gets or sets the top-left Spot used by some Panels for determining where in the shape other objects may be placed.More... The value is normally Spot.Default, but you may want to set it to override the value that many figures use.
spot2 {Spot}	Gets or sets the bottom-right Spot used by some Panels for determining where in the shape other objects may be placed.More... The value is normally Spot.Default, but you may want to set it to override the value that many figures use.
stroke {string\|Brush}	Gets or sets the Brush or string that describes how the geometry is drawn as if by a pen.More... The default value is "black", causing the shape to be outlined in black. Any valid CSS string can specify a solid color, and the Brush class can be used to specify a gradient or pattern. A null stroke will mean no stroke is drawn. A "transparent" stroke is useful when wanting to allow a shape to be pickable without obscuring any other objects behind it. More information about the syntax of CSS color strings is available at: CSS colors (mozilla.org). The stroke is drawn after the geometry is filled with the fill Brush.
strokeCap {string}	Gets or sets the style for how the ends of the stroke's line are drawn.More... The value must be one of "butt", "round", or "square". The default is "butt". For more information, see Stroke Line Cap (w3.org).
strokeDashArray {Array.\|null} 1.1	Gets or sets the dash array for creating dashed or dotted lines.More... The 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. For more information, see Stroke Line Dash Array (w3.org). The default value is null, resulting in a line without dashes or dots. Setting an array with all zeroes will set the value to null.
strokeDashOffset {number} 1.1	Gets or sets the offset for dashed lines, used to start the drawing of the dash pattern with some space.More... The value must be a real non-negative number. The default is zero. For more information, see Stroke Line Dash Offset (w3.org).
strokeJoin {string}	Gets or sets the type of corner that will be drawn for a stroke at the intersection of two straight segments of the geometry.More... The value must be one of "miter", "bevel", or "round". The default is "miter". For more information, see Stroke Line Join (w3.org).
strokeMiterLimit {number}	Gets or sets the style for the stroke's mitre limit ratio.More... The value must be a real number greater than or equal to one. The default is 10.0. For more information, see Stroke Miter Limit (w3.org).
strokeWidth {number}	Gets or sets the thickness of the stroke's pen.More... Value must be a real number greater than or equal to zero. The default value is 1.0. A value of zero will cause the stroke not to be drawn. The stroke width will affect the GraphObject.measuredBounds and GraphObject.actualBounds of this shape. The stroke is drawn centered on the path of the geometry.
toArrow {string}	Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link.More... Value must be a string. The default is "None", which means that this Shape is not an arrowhead, causing it to be the default Shape, a large filled Rectangle. If you want to have an arrowhead Shape but sometimes not show an arrowhead, you can set or bind the GraphObject.visible property, or you can set or bind this "toArrow" property to be the empty string. The arrowhead named "", an empty string, will display as nothing. The name can be any case but will always be canonicalized when set. For instance, setting "opentriangle" will set the value of the arrowhead to "OpenTriangle". All of the predefined arrowheads are shown in the Arrowheads sample. Setting this property may also set the GraphObject.segmentIndex, GraphObject.segmentOrientation, and GraphObject.alignmentFocus properties. This shape should be an element of a Link. At most one of the following three properties may be set to a non-"None" value at the same time on the same shape: figure, toArrow, fromArrow. You can define your own named arrowheads by calling the static function Shape.defineArrowheadGeometry. You can see a copy of all of the built-in arrowhead definitions in this file: Arrowheads.js.

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, enabledChanged, Fill, fromEndSegmentLength, fromLinkable, fromLinkableDuplicates, fromLinkableSelfNode, fromMaxLinks, fromShortLength, fromSpot, height, Horizontal, isActionable, isPanelMain, layer, margin, maxSize, measuredBounds, minSize, mouseDragEnter, mouseDragLeave, mouseDrop, mouseEnter, mouseHold, mouseHover, mouseLeave, mouseOver, name, None, opacity, panel, part, pickable, portId, position, row, rowSpan, scale, segmentFraction, segmentIndex, segmentOffset, segmentOrientation, shadowVisible, stretch, toEndSegmentLength, toLinkable, toLinkableDuplicates, toLinkableSelfNode, toMaxLinks, toolTip, toShortLength, toSpot, Uniform, UniformToFill, Vertical, visible, width

Method Summary Details

Name, Return Type	Description
<static> Shape.defineArrowheadGeometry(name, pathstr) 1.5	This static function defines a named arrowhead geometry.More... Once this is called one can use the name as a value for Shape.toArrow or Shape.fromArrow. The first argument is the new arrowhead name and must be a non-empty string that starts with a capital letter and that is not "None". If the second argument is a string, it is converted into a Geometry by calling `go.Geometry.parse(pathstr, false)`, which may throw an error if there are problems with the syntax of the string. Parameters: {string} name a capitalized arrowhead name ("OpenTriangle"); must not be "" or "None" {Geometry\|string} pathstr a Geometry or a Geometry path string, e.g. "m 0,0 l 8,4 -8,4"
<static> Shape.defineFigureGenerator(name, func) 1.5	This static function defines a named figure geometry generator for Shapes.More... Once this is called one can use the name as a value for Shape.figure. The first argument is the new figure name and must be a non-empty string that starts with a capital letter and that is not "None". If the second argument is a string this call defines a synonym for an existing figure generator. Do not define cycles of synonyms -- the behavior will be undefined. If the second argument is a function, the Geometry generator function's first argument is the Shape for which the function is producing a Geometry. But this Shape argument may be null in some circumstances. The second and third arguments are the desired width and height. These will always be finite non-negative numbers. The function may look at the Shape.parameter1 and Shape.parameter2 properties, which may be NaN, to decide what geometry to create for the figure given its intended width and height. The function must return a Geometry; you may want to set Geometry.spot1 and Geometry.spot2 on it to indicate where content should be placed within the figure when using an "Auto" Panel. For some figures you may also want to set Geometry.defaultStretch to GraphObject.Uniform in order to maintain the geometry's aspect ratio within the Shape. Parameters: {string} name a capitalized figure name ("RoundedRectangle"); must not be "" or "None" {function(Shape, number, number):Geometry\|string} func A function that takes (Shape,width,height) and returns a Geometry, or an existing figure generator name for which the new name will be a synonym.
<static> Shape.getArrowheadGeometries() {Map.} 1.5	This static function returns a read-only Map of named arrowhead geometries.More... The keys are arrowhead names. The values are Geometry objects. The predefined arrowheads can be seen in the Arrowheads sample. Returns: {Map.}
<static> Shape.getFigureGenerators() {Map.} 1.5	This static function returns a read-only Map of named geometry generators.More... The keys are figure names. The values are either string synonyms for other figure names, or functions that take a Shape and a width and a height and return a Geometry. The predefined shape figures can be seen in the Shapes sample. Returns: {Map.} ))

Methods borrowed from class GraphObject:: bind, copy, getDocumentAngle, getDocumentPoint, getDocumentScale, getLocalPoint, isContainedBy, isEnabledObject, isVisibleObject, setProperties