op_anim_igp_text_draw()
Abstract
Draws a text string at the specified position within a viewer, using the specified graphical properties.
Syntax
op_anim_igp_text_draw (anvid, props, x, y, text)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The text will be displayed in the viewer’s window.] |
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 to be drawn |
Return Type
Andid
drawing ID of text
[Retained drawings are issued IDs so they can later be erased (see Reference section). For a drawing to be retained, the graphical property flag OPC_ANIM_RETAIN must be passed. Non-retained drawings are issued the ID constant OPC_ANIM_ID_NIL.]
Example
/** Draw the OSI 7-layer protocol stack. **/
/* Setup argument values. */
x = 100, y = 100;
w = 400, h = 50;
rfprops = OPC_ANIM_RETAIN | OPC_ANIM_COLOR_GREEN;
rdprops = OPC_ANIM_RETAIN | OPC_ANIM_COLOR_YELLOW;
tprops = OPC_ANIM_RETAIN | OPC_ANIM_COLOR_YELLOW |
OPC_ANIM_ALIGNH_CENTER | OPC_ANIM_ALIGNV_CENTER;
/* Loop through each layer. */
for (i = 0; i < 7; i++, y += h)
{
op_anim_igp_rect_fill (vid, rfprops, " ", x, y, w, h);
op_anim_igp_rect_draw (vid, rdprops, x, y, w, h);
op_anim_igp_text_draw (vid, tprops, x + (w / 2), y + (h / 2),
Stack_Name [i]);
}
Details
Text drawings are affected by the color, bgcolor (background color), pixop, retain, font, and style graphical properties. The color and bgcolor graphical properties of the 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 strip of text 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 when the rectangle drawing will later be erased). Text drawings with the retain graphical property set (OPC_ANIM_RETAIN) will be redrawn whenever the associated viewer window is redrawn; by default, they will simply disappear.
The size of the text can be set using the font graphical property (accepted values have the format OPC_ANIM_FONT_OPEN_<ptsize>, where <ptsize> can be 10, 12, 14, 18, or 24). If you use this method, you must set the window system font by including the “open” font environment attributes (these have the format fn_x_open_<size>pt) in your 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. The 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 as part of an animation. 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. Some of these applications require the loading of model object positions into macro registers via the KP op_anim_mme_nobj_pos().
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
textargument) - Diagnostic Error: Animation viewer ID (
<anvid>) is out-of-range. (due to an invalid value for theanvidargument) - Diagnostic Error: Invalid property component (
<prop_comp>) for graphical primitive. (due to an inapplicable or invalid value for thepropsargument) - Diagnostic Error: Kernel procedure argument (
<arg_name>) has out-of-range value (<value>). (due to a value for the argumentsxorythat exceeds the range of a short integer)
Reference
- Use the KP op_anim_mgp_text_draw() to draw text within the context of a macro
- Use the KP op_anim_igp_drawing_erase() to erase and deallocate a retained text string from this KP
- Use the KPs op_anim_viewer_open() or op_anim_viewer_open_std() to obtain the ID of a newly created animation viewer (or rendezvous with a previously opened viewer), or the KP op_anim_lprobe_anvid() to obtain the ID of a viewer opened by a labeled custom animation probe, or the symbolic constant
OPC_ANIM_ANVID_PBSPECto obtain a viewer ID from an active unlabeled custom animation probe