A newly constructed Shape has a default figure of "None", which constructs a rectangular geometry, and is filled and stroked with a black brush.
Common usage:
new go.Shape("RoundedRectangle", {
strokeWidth: 2,
stroke: "red",
fill: "yellow"
})
Or when using a custom geometryString instead of a figure:
new go.Shape({
fill: "red",
stroke: null,
width: 100,
height: 100,
// This SVG-style path creates a thick "+" figure:
geometryString: "F M2 1 h1 v1 h1 v1 h-1 v1 h-1 v-1 h-1 v-1 h1 z"
})
Also common is to set some or all of the Shape properties dynamically, in the Node data, by way of bindings:
// A Node used as the node template, holding a single shape
// The shape has many bindings
myDiagram.nodeTemplate =
new go.Node("Horizontal")
.add(
new go.Shape()
.bind("width")
.bind("height")
.bind("fill", "color") // binds the data.color to shape.fill
.bind("figure"));
// It could be used with model data like this:
myDiagram.model = new go.GraphLinksModel(
[
{ key: "1", width: 150, height: 150, color: "red", figure: "Triangle" },
{ key: "2", width: 24, height: 24, color: "blue", figure: "Roundedrectangle" }
]);
The shape's figure, a predefined geometry. If no geometry is set then shapes will use the default figure of "None", a rectangle. Common values are "Rectangle", "Ellipse", "RoundedRectangle".
Optional initialization properties.
A newly constructed Shape has a default figure of "None", which constructs a rectangular geometry, and is filled and stroked with a black brush.
Optional initialization properties.
Gets or sets the figure name, used to construct a Geometry. 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.
Gets or sets the Brush or string that describes how the geometry is filled when drawn.
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.
Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link. Value must be a string. For bi-directional links the arrowhead name often starts with "Backward...".
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.
Gets or sets the Shape's Geometry that defines the Shape's figure. 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.
Gets or sets how the shape's geometry is proportionally created given its computed size. 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.
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. 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.
Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this kind of tick should end. The default is 1. Any new value should range from 0 to 1.
Gets or sets the function to determine which values along a "Graduated" Panel will be skipped. The default is null and doesn't skip any ticks.
The function takes a number argument, a value between Panel.graduatedMin and Panel.graduatedMax, and this Shape. The function will return a boolean, whether the tick will be skipped at the value of the argument.
Note that the second argument is the Shape, not a particular tick that would be rendered at the given value. The function, if supplied, must not have any side-effects.
Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this kind of tick should start. The default is 0. Any new value should range from 0 to 1.
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. The default is 1. Any new value must be a positive integer.
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. 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.
This read-only property returns the natural bounds of this Shape as determined by its geometry's bounds. The bounds will always include the (0,0) point. If the desiredSize is set, it returns a Rect with the desiredSize. If no geometry is available, and no desiredSize is set, this may have NaN values for the width and height.
Gets or sets a property for parameterizing the construction of a Geometry from a figure. The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.
Gets or sets a property for parameterizing the construction of a Geometry from a figure. The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.
Gets or sets a GraphObject that is drawn repeatedly along the path of the stroke of this shape. 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 pathPattern object is not part of the measured bounds of the Shape, it is a cosmetic element only.
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.
This property is ignored by the Shapes in "Grid" or "Graduated" Panels.
Gets or sets the top-left Spot used by some Panels for determining where in the shape other objects may be placed. The value is normally Spot.Default, but you may want to set it to override the value that many figures use.
Gets or sets the bottom-right Spot used by some Panels for determining where in the shape other objects may be placed. The value is normally Spot.Default, but you may want to set it to override the value that many figures use.
Gets or sets the Brush or string that describes how the geometry is drawn as if by a pen.
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.
Gets or sets the style for how the ends of the stroke's line are drawn. The value must be one of "butt", "round", or "square". The default is "butt".
For more information, see Stroke Line Cap (w3.org).
Gets or sets the dash array for creating dashed or dotted lines. 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.
Gets or sets the offset for dashed lines, used to start the drawing of the dash pattern with some space. The value must be a real non-negative number. The default is zero.
For more information, see Stroke Line Dash Offset (w3.org).
Gets or sets the type of corner that will be drawn for a stroke at the intersection of two straight segments of the geometry. The value must be one of "miter", "bevel", or "round". The default is "miter".
For more information, see Stroke Line Join (w3.org).
Gets or sets the style for the stroke's mitre limit ratio. 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).
Gets or sets the thickness of the stroke's pen.
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. However, Main Shapes of Link Selection Adornments with a strokeWidth of 0 will inherit the strokeWidth from the Link's main Shape.
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.
Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link. 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.
This static function defines a named arrowhead geometry. 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.
a capitalized arrowhead name ("OpenTriangle"); must not be "" or "None"
a Geometry or a Geometry path string, e.g. "m 0,0 l 8,4 -8,4"
This static function defines a named figure geometry generator for Shapes. 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.
Generated figures must create a Geometry that is not larger than the supplied with and height. Doing so will signal an error.
a capitalized figure name ("RoundedRectangle"); must not be "" or "None"
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.
This static function returns a read-only Map of named arrowhead geometries. The keys are arrowhead names. The values are Geometry objects.
The predefined arrowheads can be seen in the Arrowheads sample.
This static function returns a read-only Map of named geometry generators. 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.
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:
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.