op_anim_igp_circle_fill()
Abstract
Draws a filled circle at the specified position within a viewer, using the specified graphical properties.
Syntax
op_anim_igp_circle_fill (anvid, props, pat_name, ctr_x, ctr_y, radius)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The circle 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.] |
pat_name |
char* |
pattern name [This string indicates an icon to be used as a pattern for the fill.] |
ctr_x |
int |
x coordinate of the circle’s center point, measured in pixels from the origin of the viewer window (upper-left corner) |
ctr_y |
int |
y coordinate of the circle’s center point, measured in pixels from the origin of the viewer window (upper-left corner) |
radius |
int |
radius of the circle [This value is a distance measured in pixels.] |
Return Type
Andid
drawing ID of circle
[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
/* Open a full-size animation viewer. */
vid = op_anim_viewer_open_std ("Source-Dest Connectivity", OPC_ANIM_LOCATION_FULL);
/* Determine the number of nodes in network model. */
node_count = op_topo_object_count (OPC_OBJMTYPE_NODE);
/* Cache the graphical property flags for circles. */
circ_props = OPC_ANIM_RETAIN | OPC_ANIM_COLOR_BLUE;
/* Loop through nodes, drawing source and destination circles for each. */
for (i = 0, ypos = 100; i < node_count; i++, ypos += 40)
{
/* Draw source circle for node. */
op_anim_igp_circle_fill (vid, circ_props, " ", xleft, ypos, 10);
/* Draw destination circle for node. */
op_anim_igp_circle_fill (vid, circ_props, " ", xright, ypos, 10);
}
Details
Filled circle drawings are affected by the color, pixop, retain, and style graphical properties. The color graphical property of the circle 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 circle 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 circle drawing will later be erased). Circle 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 pat_name argument is only referenced if the style graphical property flag OPC_ANIM_STYLE_PATTERN is specified. A pattern fill repeatedly tiles the specified icon to fill the circular area. The tiles are aligned to the absolute coordinates of the graphics display device, rather than the circle, so moving a viewer may change the relative alignment of the circle and its fill tiling. You can create icons and add them to an icon database by using the Icon Database Editor. For more information, see “Icon Database Editor“ on page 615.
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.
Purpose
Provides a mechanism to draw a filled circle as part of an animation. The circle 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. Filled circles are useful for depicting static model objects such as nodes or states in alternative diagrams, or dynamic model objects such as packets or ICIs. To represent a mobile node via a filled circle rather than its typical model icon, the node’s position can be obtained via the KP op_ima_obj_pos_get(), and this can be translated into a viewer coordinate via the KP op_anim_ime_gen_pos(). Model-independent animations such as state history maps or dynamic Petri nets can also take advantage of Igp circles.
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
pat_nameargument) - 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 argumentsctr_x,ctr_y, orradiusthat exceeds the range of a short integer)
Reference
- use op_anim_igp_circle_draw() to draw a circle outline
- use op_anim_mgp_circle_fill() to fill a circle within the context of a macro
- use op_anim_igp_drawing_erase() to erase and deallocate a retained circle created by this KP
- use 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