Functions | |
void | Define_Shape (char const *name, int definition_length, float const *definition) |
Defines a shape to be used for the background of a text annotation. More... | |
void | UnDefine_Shape (char const *name) |
Deletes the shape definition, frees any memory allocated to the shape object, and triggers a redraw on any dependent scene elements. More... | |
Detailed Description
Function Documentation
◆ Define_Shape()
void Define_Shape | ( | char const * | name, |
int | definition_length, | ||
float const * | definition | ||
) |
Defines a shape to be used for the background of a text annotation.
- Parameters
-
name - The name being assigned to this shape definition. definition_length - The number of elements contained in the definition array. definition - Array of floating point numbers representing the shape definition, including the shape type (e.g., polygon, circle, ellipse, circular arc, etc.), the number of elements in the shape definition(s), the shapes' points, radii and other related settings, and a terminal 0 at the end of the array. Please see the table below for more details.
DETAILS

The following snippet shows how to define a text box with trimmed corners:
The first number in the array is a 3, indicating that each coordinate will be defined with three numbers. The first number is a scale of the bounding in the horizontal direction of the coordinate. The second number is the the scale of the bounding in the vertical direction of the coordinate; in the case of mult-line text, the vertical bounding refers to the height of a single line of text. Lastly, the third value is a margin; by default, margins are defined such that a value of "1" would be equal to 50% of the height of a text character. (For more information on margins, including how to change the default settings and how they are applied, please see the Set_Text_Font_options function.)
The number 8 indicates that there will be 8 points used to define the polygon, with each point consisting of two coordinates. In this case, each point is defined with six numbers: the first three define the X coordinate and the last three define the Y coordinate.
Finally, a terminal 0 indicates that the definition is complete. These numbers are explained in detail in the table below.
The format codes for shapes are the following:
Format Code | Elements | Example |
---|---|---|
6 | x bounding of the coordinate, y bounding of the coordinate, and four margin values | Each coordinate of a point is defined with six numbers: 1, 0, 1, 0, 1, 0 (A point is defined with two coordinates) |
5 | x/y bounding + three margin values | 1, 0, 1, 0, -1 |
4 | x/y bounding + two margin values | 1, 0, 1, 0 |
3 | x/y bounding + one margin value | 1, 0, 1 |
2 | Single coordinate value (applies to both x and y bounding of the coordinate) | Same as format 3, except it has no margin value. |
1 | Single coordinate value (applies to both x and y bounding of the coordinate) | This format is provided for convenience; each coordinate in the point is defined with a single value: 1, 1 (Format 1 includes the default margins.) |
0 | Same as format 1. | |
-3 | x bounding of the coordinate, y bounding of the coordinate, and a radius value | 0, 1, 0.5 |
-4 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and a margin value | 0, 1, 0.5, -0.5 |
-5 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and two margin values | 0, 1, 0.5, 0, -0.5 |
-6 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and three margin values | 0, 1, 0.5, 0, 0, -0.5 |
-7 | x bounding of the coordinate, y bounding of the coordinate, a radius value, and four margin values | 0, 1, 0.5, 0, -0.5, 0 |
The Op Codes for shapes are as follows:
Type | Op Code | Required Elements | Notes |
---|---|---|---|
Polygon | 3 or higher | Three or more points | A polygon can be defined with three or more points. |
Polyline | 2 | Two points | |
Termination | 0 | None | Signals the end of the shape definition |
Ellipse | -1 | Center, semi-major point, semi-minor point | |
Circle | -2 | Center, point on edge | |
Circle3 | -3 | Three points on circumference | |
Circular Arc | -4 | Arc start, middle, end | |
Elliptical Arc | -5 | Center, semi-major point, semi-minor point, parametric start & end | |
Restart | -10 | None | Signals new loop or polyline |
Non-filled | -11 | None | All remaining pieces are line-like |
Anchor | -15 | Single point | Defines an anchor Intermediate anchor points can also be set (see below for an example) |
For an example of how to insert an anchored leader line on an annotation shape, please see the Insert_Text_Leader function.
◆ UnDefine_Shape()
void UnDefine_Shape | ( | char const * | name | ) |
Deletes the shape definition, frees any memory allocated to the shape object, and triggers a redraw on any dependent scene elements.
- Parameters
-
name - The name assigned to this shape definition.