Custom Shape Structure

• Aug 02, 2022
• 4 minutes to read

An XML-based shape consists of a template that describes the shape (this includes its geometry and optional settings).

This topic shows the base structure of an XML-based shape. For more information on how to define shapes and load them to the control’s repository, refer to the “Custom Shapes Tutorial“ topic.

Shape Description

The ShapeTemplate is the main element of an XML-based shape’s structure and contains attributes and child elements that define the shape.

The following table lists this element’s attributes:

Attribute Name	Description
ID, Caption	A shape’s unique identifier and name within the control’s repository.
DefaultSize	A shape’s default width and height in pixels.
ConnectionPoints, Parameters	Provide access to the collection of anchor points or parameters.
Rows, Columns	A shape’s row/column size in pixels. This attribute allows you to divide your shape into a grid-based layout. To enable automatic row/column size calculation, pass the “*” as the attribute value. When you resize the shape, these values are adjusted proportionally.

Shape Geometry

A geometric object is a set of lines and/or arc primitives that form a shape.

The Start, Line, and Arc child elements define a geometric object’s settings.

Start

A shape can consist of multiple geometric objects. The Start child element’s attributes allow you to specify a geometric object’s initial coordinates and adjust its appearance settings.

This child element has the following attributes:

• X

• Y

• Kind

• IsSmoothJoin

• FillBrightness

• FillColor

• StrokeColor

X and Y

The geometric object’s start coordinates in the control area.

Kind

You can choose between the following options:

Attribute Value	Description	Example
None	The geometric object’s background is transparent. You should define each primitive’s coordinates. The FillColor attribute value is ignored.
Closed	The geometric object’s background is transparent. The last primitive’s destination point corresponds to the first primitive’s start point. The FillColor attribute value is ignored.
Filled	The FillColor attribute specifies the geometric object’s background color. You should define each primitive’s coordinates.
ClosedFilled (default)	The FillColor attribute specifies the geometric object’s background color. The last primitive’s destination point corresponds to the first primitive’s start point.

IsSmoothJoin

Allows you to smooth primitive intersections.

The default value is False.

FillBrightness

The brightness level (from -1 to 1) of a geometric object’s fill color. The default value is 0.

FillColor and StrokeColor

The RGB color of a geometric object’s background and line. You can specify an HTML color using its name or color code in a hexadecimal format.

You can customize the object’s fill and stroke colors in the editor if they are not predefined in XML code.

Note

Parse routines ignore the FillColor value if the object’s kind is None or Closed.

Line

This child element contains the X and Y attributes that define each line’s destination point. The previous line’s destination point is the start point of the next line.

Arc

This child element provides the following attributes:

Attribute Name	Description
X, Y	An arc’s destination point.
Size	Specifies an arc’s width and height. This attribute uses the CreateSize function that can accept constants, variables or expressions as parameters.
Direction	Identifies whether an arc is drawn clockwise or counterclockwise. The default value is Counterclockwise.

Shape Optional Settings

Optional settings include the ConnectionPoints and Parameters child elements.

ConnectionPoints

This child element provides access to the collection of points that serve as anchors that allow you to bind a connection to the shape.

To change an individual point’s settings, use the ShapePoint sub-element and its attributes:

Attribute Name	Description
X, Y	An anchor point’s position within the shape’s area.
Kind	Specifies whether anchor point’s coordinates are calculated relative to a shape size (relative) or drawing area (absolute). The default value is Relative.

Parameters Element

XML-based shapes can have user-customizable geometry. To enable this, set the fcoUseShapeParameters item to True in the control’s options and use the Parameters child element to access the parameters collection.

Each shape can have a maximum of ten parameters that you can pass as the P0…P9 variables to an attribute’s value.

A parameter appears as a yellow handle that you can move to transform the shape. Click the handle and hold down the left mouse button to drag it.

To adjust an individual parameter’s settings, use the Parameter sub-element and the following attributes:

Attribute Name	Description
DefaultValue	A parameter’s initial value (P parameter within the Point attribute).
Value	Allows you to obtain a parameter’s value when user drags the handle.
Point	A handle’s position within a shape’s area. This attribute uses the CreatePoint function that accepts the handle’s X and Y coordinates as parameters.
Min, Max	A parameter’s threshold values. Limits the handle’s movement.