Define_Shape

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

corner_trimmed_box.png

The following snippet shows how to define a text box with trimmed corners:

float const clipped[] = {
3,
8,
1, 0, 1, 0, 1, 0,
1, 0, 0, 0, 1, 1,
-1, 0, 0, 0, 1, 1,
-1, 0, -1, 0, 1, 0,
-1, 0, -1, 0, -1, 0,
-1, 0, 0, 0, -1, -1,
1, 0, 0, 0, -1, -1,
1, 0, 1, 0, -1, 0,
0
};
HC_Define_Shape("clipped", countof(clipped), clipped);
HC_Open_Segment("clipped");
HC_Set_Text_Font("background=shape=clipped");
HC_Insert_Text(-0.8, 0.8, 0, "corner trimmed box");
HC_Close_Segment();

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.