op_anim_igp_line_draw()
Abstract
Draws a line segment between two specified points within a viewer, using the specified graphical properties.
Syntax
op_anim_igp_line_draw (anvid, props, x1, y1, x2, y2)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The line segment 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.] |
x1 |
int |
x coordinate of line’s first endpoint¹ |
y1 |
int |
y coordinate of line’s first endpoint¹ |
x2 |
int |
x coordinate of line’s second endpoint¹ |
y2 |
int |
y coordinate of line’s second endpoint¹ |
Note 1: Measured in pixels from the origin of the viewer window (upper-left corner)
Return Type
Andid
drawing ID of line
[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 a symbol that represents queue saturation. **/
/** (symbol is a square containing an X) **/
sym_props = OPC_ANIM_COLOR_BLUE | OPC_ANIM_RETAIN;
/* Draw square. */
op_anim_igp_line_draw (vid, sym_props, xpos - 20, ypos - 20, xpos + 20,
ypos - 20);
op_anim_igp_line_draw (vid, sym_props, xpos - 20, ypos + 20, xpos + 20,
ypos + 20);
op_anim_igp_line_draw (vid, sym_props, xpos - 20, ypos - 20, xpos - 20,
ypos + 20);
op_anim_igp_line_draw (vid, sym_props, xpos + 20, ypos - 20, xpos + 20,
ypos + 20);
/* Draw X. */
op_anim_igp_line_draw (vid, sym_props, xpos - 20, ypos - 20, xpos + 20,
ypos + 20);
op_anim_igp_line_draw (vid, sym_props, xpos - 20, ypos + 20, xpos + 20,
ypos - 20);
/* Make sure the requests are displayed together on screen. */
op_anim_force ();
Details
Line drawings are affected by the color, pixop, style, and retain graphical properties. The color graphical property of the line 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 is black). If the pixop graphical property is set to a value other than the default (OPC_ANIM_PIXOP_SRC), portions of the line which are drawn over non-black viewer pixels may be displayed in a color other than that assigned (note that the pixop value OPC_ANIM_PIXOP_XOR should be used when the line drawing will later be erased). The style graphical property of a line can take on one of three values: solid lines can be specified by the symbolic constant OPC_ANIM_STYLE_SOLID (the default), dashed lines by OPC_ANIM_STYLE_DASHES, and dotted lines by OPC_ANIM_STYLE_DOTS. Line 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 special value identified by the symbolic constant OPC_ANIM_ID_NIL is returned by this KP if the retain graphical property is not enabled, or if KP execution is disabled due to the lack of a custom animation probe, or the presence of a custom animation probe which is not currently active.
In addition to the sources of viewer IDs listed in the Reference section, the symbolic constant OPC_ANIM_ANVID_PBSPEC can be used as a substitute viewer ID, indicating that the real viewer ID should be obtained from an active unlabeled custom animation probe.
Purpose
Provides a mechanism to draw a line segment as part of an animation. The line segment 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. Line drawings are useful for depicting dynamic connections between model diagram components: examples include remote interrupts, packet deliveries, radio transmissions, and established circuits. However, these applications are best performed by drawing a line within a macro via the KP op_anim_mgp_line_draw(), since the position of model objects can be directly obtained in a macro via the KP op_anim_mme_nobj_pos(). Model-independent animations such as state transition maps or peer-to-peer transmission logs can take advantage of Igp lines.
Errors
- 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 argumentsx1,y1,x2, ory2that exceeds the range of a short integer)
Reference
- Use the KP op_anim_igp_rect_draw() to draw a square or rectangle
- Use the KP op_anim_mgp_line_draw() to draw a line within the context of a macro
- Use the KP op_anim_igp_drawing_erase() to erase and deallocate a retained line created by 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