Class Shape

GoDiagram®
v10.0.8
by Northwoods Software®

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.

Inheritance

object

GraphObject

Shape

Implements

IHasContextMenu

IHasToolTip

Namespace: Northwoods.Go

Assembly: Northwoods.GoDiagram.WinForms.dll

Syntax

public class Shape : GraphObject, IHasContextMenu, IHasToolTip

Remarks

There are generally two types of shapes: Those that use a custom Geometry by setting 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:

// A shape with the figure set to RoundedRectangle:
new Shape("RoundedRectangle") { Fill = "lightgreen" }

// A shape with a custom geometry, using Geometry:
new Shape { Geometry = Geometry.Parse("M120 0 L80 80 0 50z") }

// A shape with a custom geometry, using GeometryString:
new 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 =
  new Link()
    .Add(
      // 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
      new Shape { StrokeWidth = 2, Stroke = "gray" },
      new 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 DefineFigureGenerator(string, Func<Shape, double, double, Geometry>). Get a dictionary of named figures by calling the static function GetFigureGenerators().

All of the predefined arrowheads are shown in the Arrowheads sample. You can define your own named arrowheads by calling the static function DefineArrowheadGeometry(string, Geometry). Get a dictionary of named arrowheads by calling the static function GetArrowheadGeometries().

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

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.

Constructors

Shape()

Constructs a Shape with a Figure of "None", which uses a rectangular geometry, and fills and strokes with a black brush.

Declaration

public Shape()

Shape(string)

Constructs a Shape with the given Figure, and fills and strokes with a black brush.

Declaration

public Shape(string fig)

Parameters

Type	Name	Description
string	fig

Properties

Figure

Gets or sets the figure name, used to construct a Geometry.

Declaration

public string Figure { get; set; }

Property Value

Type	Description
string

Remarks

The value must be a string. The default value is "None".

The name can be any case. 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 DefineFigureGenerator(string, Func<Shape, double, double, Geometry>).

Fill

Gets or sets the Brush that describes how the geometry is filled when drawn.

Declaration

public Brush Fill { get; set; }

Property Value

Type	Description
Brush

Remarks

The default value is a solid black brush, 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

Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link.

Declaration

public string FromArrow { get; set; }

Property Value

Type	Description
string

Remarks

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 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. All of the predefined arrowheads are shown in the Arrowheads sample.

Setting this property may also set the SegmentIndex, SegmentOrientation, and 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 DefineArrowheadGeometry(string, Geometry).

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

Geometry

Gets or sets the Shape's Geometry that defines the Shape's figure.

Declaration

public Geometry Geometry { get; set; }

Property Value

Type	Description
Geometry

Remarks

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.

GeometryStretch

Gets or sets how the shape's geometry is proportionally created given its computed size.

Declaration

public GeometryStretch GeometryStretch { get; set; }

Property Value

Type	Description
GeometryStretch

Remarks

Possible values are None, Fill, Uniform, and Default. The default is Default, which resolves to Fill for most figures, though some regular figures such as "Circle" and "Square" default to Uniform.

GeometryString

When set, creates a Geometry and normalizes it from a given path string, then sets the Geometry property on this Shape and set the Position to the amount computed by normalization.

Declaration

public string GeometryString { get; set; }

Property Value

Type	Description
string

Remarks

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.

GraduatedSkip

Gets or sets the function to determine which values along a "Graduated" Panel will be skipped.

Declaration

public Func<double, GraphObject, bool> GraduatedSkip { get; set; }

Property Value

Type	Description
Func<double, GraphObject, bool>

Remarks

The default is null and doesn't skip any ticks.

The function takes a number argument, a value between GraduatedMin and GraduatedMax, and this Shape. The function will return a bool, whether the tick will be skipped at the value of the argument.

Note that the second argument is not a particular tick that would be rendered at the given value. The function, if supplied, must not have any side-effects.

Interval

Gets or sets how frequently this shape should be drawn within a "Grid" or "Graduated" Panel, in multiples of the GridCellSize or GraduatedTickUnit.

Declaration

public int Interval { get; set; }

Property Value

Type	Description
int

Remarks

The default is 1. Any new value must be a positive integer.

IsGeometryPositioned

Gets or sets the whether the Position of this shape denotes the top-left corner of this shape in panel coordinates or the origin of this geometry's coordinate system.

Declaration

public bool IsGeometryPositioned { get; set; }

Property Value

Type	Description
bool

Remarks

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

This read-only property returns the natural bounds of this Shape as determined by its Geometry's bounds.

Declaration

public override Rect NaturalBounds { get; }

Property Value

Type	Description
Rect

Overrides

GraphObject.NaturalBounds

Remarks

The bounds will always include the (0,0) point. If the DesiredSize is set, this 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.

Parameter1

Gets or sets a property for parameterizing the construction of a Geometry from a figure.

Declaration

public double Parameter1 { get; set; }

Property Value

Type	Description
double

Remarks

The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.

Parameter2

Gets or sets a property for parameterizing the construction of a Geometry from a figure.

Declaration

public double Parameter2 { get; set; }

Property Value

Type	Description
double

Remarks

The meaning of this property depends on the particular figure. The value must be a number; the default value is NaN.

PathPattern

Gets or sets a GraphObject that is drawn repeatedly along the path of the stroke of this shape.

Declaration

public GraphObject PathPattern { get; set; }

Property Value

Type	Description
GraphObject

Remarks

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 Shapes in "Grid" or "Graduated" Panels.

Spot1

Gets or sets the top-left Spot used by some Panels for determining where in the shape other objects may be placed.

Declaration

public Spot Spot1 { get; set; }

Property Value

Type	Description
Spot

Remarks

The value is normally Default, but you may want to set it to override the value that many Figures use.

Spot2

Gets or sets the bottom-right Spot used by some Panels for determining where in the shape other objects may be placed.

Declaration

public Spot Spot2 { get; set; }

Property Value

Type	Description
Spot

Remarks

The value is normally Default, but you may want to set it to override the value that many Figures use.

Stroke

Gets or sets the Brush that describes how the geometry is drawn as if by a pen.

Declaration

public Brush Stroke { get; set; }

Property Value

Type	Description
Brush

Remarks

The default value is a solid black brush, 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

Gets or sets the style for how the ends of the stroke's line are drawn.

Declaration

public LineCap StrokeCap { get; set; }

Property Value

Type	Description
LineCap

Remarks

Possible values are Butt, Round, or Square. The default is Butt.

StrokeDashArray

Gets or sets the dash array for creating dashed or dotted lines.

Declaration

public float[] StrokeDashArray { get; set; }

Property Value

Type	Description
float[]

Remarks

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

Gets or sets the offset for dashed lines, used to start the drawing of the dash pattern with some space.

Declaration

public float StrokeDashOffset { get; set; }

Property Value

Type	Description
float

Remarks

The value must be a real non-negative number. The default is zero.

For more information, see Stroke Line Dash Offset (w3.Org).

StrokeJoin

Gets or sets the type of corner that will be drawn for a stroke at the intersection of two straight segments of the geometry.

Declaration

public LineJoin StrokeJoin { get; set; }

Property Value

Type	Description
LineJoin

Remarks

Possible values are Miter, Bevel, or Round. The default is Miter.

StrokeMiterLimit

Gets or sets the style for the stroke's mitre limit ratio.

Declaration

public double StrokeMiterLimit { get; set; }

Property Value

Type	Description
double

Remarks

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

Gets or sets the thickness of the stroke's pen.

Declaration

public double StrokeWidth { get; set; }

Property Value

Type	Description
double

Remarks

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 MeasuredBounds and ActualBounds of this shape. The stroke is drawn centered on the path of the geometry.

ToArrow

Gets or sets the name of the kind of arrowhead that this shape should take when this shape is an element of a Link.

Declaration

public string ToArrow { get; set; }

Property Value

Type	Description
string

Remarks

Value must be a string.

The name can be any case. All of the predefined arrowheads are shown in the Arrowheads sample.

Setting this property may also set the SegmentIndex, SegmentOrientation, and 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 DefineArrowheadGeometry(string, Geometry).

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

Methods

DefineArrowheadGeometry(string, Geometry)

This static function defines a named arrowhead geometry.

Declaration

public static void DefineArrowheadGeometry(string name, Geometry geo)

Parameters

Type	Name	Description
string	name	an arrowhead name ("OpenTriangle"); must not be "" or "None"
Geometry	geo	a Geometry

Remarks

Once this is called one can use the name as a value for ToArrow or FromArrow.

DefineArrowheadGeometry(string, string)

This static function defines a named arrowhead geometry.

Declaration

public static void DefineArrowheadGeometry(string name, string pathstr)

Parameters

Type	Name	Description
string	name	an arrowhead name ("OpenTriangle"); must not be "" or "None"
string	pathstr	a Geometry path string, e.g. "m 0,0 l 8,4 -8,4"

Remarks

Once this is called one can use the name as a value for ToArrow or FromArrow.

The second argument is converted into a Geometry by calling Geometry.Parse(pathstr, false), which may throw an error if there are problems with the syntax of the string.

DefineFigureGenerator(string, Func<Shape, double, double, Geometry>)

This static function defines a named figure geometry generator for Shapes. Once this is called one can use the name as a value for Figure.

Declaration

public static void DefineFigureGenerator(string name, Func<Shape, double, double, Geometry> func)

Parameters

Type	Name	Description
string	name	a figure name ("RoundedRectangle"); must not be "" or "None"
Func<Shape, double, double, Geometry>	func	A function that takes (Shape, width, height) and returns a Geometry

Remarks

The first argument is the new figure name and must be a non-empty string that is not "None".

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 Parameter1 and 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 Spot1 and 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 DefaultStretch to 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 width and height. Doing so will signal an error.

DefineFigureGenerator(string, string)

This static function defines a named figure geometry generator for Shapes. Once this is called one can use the name as a value for Figure.

Declaration

public static void DefineFigureGenerator(string name, string synonym)

Parameters

Type	Name	Description
string	name	a figure name ("RoundedRectangle"); must not be "" or "None"
string	synonym	An existing figure generator name for which the new name will be a synonym.

Remarks

The first argument is the new figure name and must be a non-empty string 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.

GetArrowheadGeometries()

This static function returns a read-only dictionary of named arrowhead geometries.

Declaration

public static IReadOnlyDictionary<string, Geometry> GetArrowheadGeometries()

Returns

Type	Description
IReadOnlyDictionary<string, Geometry>

Remarks

The keys are arrowhead names. The values are Geometry objects.

The predefined arrowheads can be seen in the Arrowheads sample.

GetFigureGenerators()

This static function returns a read-only dictionary of named geometry generators.

Declaration

public static IReadOnlyDictionary<string, Func<Shape, double, double, Geometry>> GetFigureGenerators()

Returns

Type	Description
IReadOnlyDictionary<string, Func<Shape, double, double, Geometry>>

Remarks

The keys are figure names. The values are 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.

Implements

IHasContextMenu

IHasToolTip

Class Shape

Inheritance

Implements

Namespace: Northwoods.Go

Assembly: Northwoods.GoDiagram.WinForms.dll

Syntax

Remarks

Constructors

Shape()

Declaration

Shape(string)

Declaration

Parameters

Properties

Figure

Declaration

Property Value

Remarks

Fill

Declaration

Property Value

Remarks

FromArrow

Declaration

Property Value

Remarks

Geometry

Declaration

Property Value

Remarks

See Also

GeometryStretch

Declaration

Property Value

Remarks

GeometryString

Declaration

Property Value

Remarks

GraduatedSkip

Declaration

Property Value

Remarks

Interval

Declaration

Property Value

Remarks

IsGeometryPositioned

Declaration

Property Value

Remarks

NaturalBounds

Declaration

Property Value

Overrides

Remarks

Parameter1

Declaration

Property Value

Remarks

Parameter2

Declaration

Property Value

Remarks

PathPattern

Declaration

Property Value

Remarks

Spot1

Declaration

Property Value

Remarks

Spot2

Declaration

Property Value

Remarks

Stroke

Declaration

Property Value

Remarks