op_anim_mgp_text_draw()
Abstract
Adds a primitive that draws a text string to the specified macro.
Syntax
op_anim_mgp_text_draw (anmid, props, x, y, text)
| Argument | Type | Description |
|---|---|---|
anmid |
Anmid |
macro ID [This value is a numeric identifier which references an open animation macro, created via the KP op_anim_macro_create().] |
props |
int |
graphical property flags [This value is the bitwise OR combination of the Animation Graphical Properties flags OPC_ANIM_COLOR_*, OPC_ANIM_PIXOP_*, OPC_ANIM_BGCOLOR_*, OPC_ANIM_STYLE_*, OPC_ANIM_ALIGNH_*, OPC_ANIM_ALIGNV_*, OPC_ANIM_FONT_*, and OPC_ANIM_RETAIN. For more information, see “Animation“ on page 3.] |
x |
int |
x coordinate of text position, measured in pixels from the origin of the viewer window (upper-left corner) |
y |
int |
y coordinate of text position, measured in pixels from the origin of the viewer window (upper-left corner) |
text |
char* |
text string |
Return Type
void
no return value
Example
/** Construct a macro which depicts a field within a packet. **/
mid = op_anim_macro_create ("pk field");
/* Draw a rectangle fixed at (X,Y) which has width(W) = no. bits(B) x 8 */
op_anim_mgp_reg_set (mid, OPC_ANIM_REG_C_INT, 8);
op_anim_mgp_arop (mid, OPC_ANIM_REG_B_INT, OPC_ANIM_AROP_MULTIPLY,
OPC_ANIM_REG_C_INT, OPC_ANIM_REG_W_INT);
op_anim_mgp_rect_draw (mid, OPC_ANIM_COLOR_RED, OPC_ANIM_REG_X_INT,
OPC_ANIM_REG_Y_INT, OPC_ANIM_REG_W_INT, 15);
/* Draw the field name at (L,Y) where L = X + (W / 2) */
op_anim_mgp_reg_set (mid, OPC_ANIM_REG_C_INT, 2);
op_anim_mgp_arop (mid, OPC_ANIM_REG_W_INT, OPC_ANIM_AROP_DIVIDE, OPC_ANIM_REG_C_INT,
OPC_ANIM_REG_H_INT);
op_anim_mgp_arop (mid, OPC_ANIM_REG_X_INT, OPC_ANIM_AROP_ADD, OPC_ANIM_REG_H_INT,
OPC_ANIM_REG_L_INT);
op_anim_mgp_text_draw (mid, OPC_ANIM_ALIGNH_CENTER | OPC_ANIM_ALIGNV_BOTTOM |
OPC_ANIM_FONT_OPEN_10 | OPC_ANIM_COLOR_RED,
OPC_ANIM_REG_L_INT, OPC_ANIM_REG_Y_INT, OPC_ANIM_REG_S_STR);
op_anim_macro_close (mid);
Details
The props, x, y, and text arguments of this KP will accept macro register ID symbolic constants, such as those listed in Table 42 “Animation Macro Register Identifier Symbolic Constants—Integer Values“ on page 8. If register IDs are supplied for these arguments, the actual values are taken from the specified registers at the time of macro invocation. Text drawings are affected by the color, bgcolor (background color), pixop, font, and style graphical properties. The color and bgcolor properties of text can be assigned any of the 64 indexed color values (with the format OPC_ANIM_COLOR_RGB<rgb>) or the 25 named color values (the default color and bgcolor values are black). The background color of a text string appears in a bounding rectangle around the text which fills in the pixels between the individual characters; this can be used to match the text strip to a colored background.
If the pixop graphical property is set to a value other than the default (OPC_ANIM_PIXOP_SRC), portions of the text which are drawn over non-black viewer pixels may be displayed in colors other than those assigned (note that the pixop value OPC_ANIM_PIXOP_XOR should be used if the specified macro will be invoked with the retain property for later erasure).
Text size can be set using the font graphical property (values have the format OPC_ANIM_FONT_OPEN_<ptsize>, where <ptsize> can be 10, 12, 14, 18, or 24). The window system font of the text is set via the “open” font environment attributes with the format fn_x_open_<size>pt in the preferences file. The horizontal and vertical alignment of the text with respect to the specified point can be set using the style graphical property. The property formats are: OPC_ANIM_ALIGNH_<h>, where <h> is either LEFT, CENTER, or RIGHT, and OPC_ANIM_ALIGHV_<v>, where <v> is either TOP, CENTER, or BOTTOM. Default alignments are horizontally left (text left edge at point) and vertically top (text top edge at point).
Purpose
Provides a mechanism to draw a line of text in the context of a macro. The text can serve as a component in a completely customized display, or it can be added to a model diagram as an indicator of some dynamic event or status. Text is useful in an animation for displaying dynamic simulation conditions (e.g., queue overflows, routing updates, protocol states), for displaying statistics (e.g., queue sizes, number of collisions, average throughput or delay), and for labeling diagram objects.
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
textargument) - Recoverable Error: Animation macro ID (
<anmid>) is [out-of-range] [unrecognized]. (former case due toanmidargument value that is invalid, latter case to destroyed macro) - Diagnostic Error: Invalid property component (
<prop_comp>) for graphical primitive. (due to an inapplicable or invalid literal value for thepropsargument) - Diagnostic Error: Kernel procedure argument (
<arg>) has out-of-range value (<val>). (due to a literal value for the argumentsxorythat exceeds the range of a short)
Reference
- Use the KP op_anim_igp_text_draw() to draw text in immediate mode
- Use the KP op_anim_macro_create() to create an empty macro
- Use the KP op_anim_macro_close() to indicate the completion of a macro definition
- Use the KP op_anim_igp_macro_draw() to invoke a macro within a viewer