Custom Shape Structure
- 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. |