op_anim_mgp_rect_fill()
Abstract
Adds a primitive that draws a filled rectangle to the specified macro.
Syntax
op_anim_mgp_rect_fill (anmid, props, pat_name, x, y, width, height)
| 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.] |
pat_name |
char* |
pattern name |
x |
int |
x coordinate of rectangle upper-left corner |
y |
int |
y coordinate of rectangle upper-left corner [The x and y coordinates are measured in pixels from the origin of the viewer window (upper-left corner).] |
width |
int |
width of rectangle (in pixels) |
height |
int |
height of rectangle (in pixels) |
Return Type
void
no return value
Example
/** Construct a macro which depicts a blown-up state. **/
mid = op_anim_macro_create ("mega-state");
/* Fill the state’s circle centered at (X,Y). */
op_anim_mgp_circle_fill (mid, OPC_ANIM_COLOR_RED, " ",
OPC_ANIM_REG_X_INT, OPC_ANIM_REG_Y_INT, 200);
/* Draw the state’s inner ridge centered at (X,Y). */
op_anim_mgp_circle_draw (mid, OPC_ANIM_COLOR_BLACK,
OPC_ANIM_REG_X_INT, OPC_ANIM_REG_Y_INT, 200);
/* Fill the state’s label box at (M,N) (centered at (X,Y)). */
op_anim_mgp_reg_set (mid, OPC_ANIM_REG_W_INT, (180 / 2));
op_anim_mgp_arop (mid, OPC_ANIM_REG_X_INT, OPC_ANIM_AROP_SUBTRACT,
OPC_ANIM_REG_W_INT, OPC_ANIM_REG_M_INT);
op_anim_mgp_reg_set (mid, OPC_ANIM_REG_H_INT, (40 / 2));
op_anim_mgp_arop (mid, OPC_ANIM_REG_Y_INT, OPC_ANIM_AROP_SUBTRACT,
OPC_ANIM_REG_H_INT, OPC_ANIM_REG_N_INT);
op_anim_mgp_rect_fill (mid, OPC_ANIM_COLOR_BLACK, OPC_ANIM_REG_M_INT,
OPC_ANIM_REG_N_INT, 180, 40);
/* ... */
Details
The props, pat_name, x, y, width, and height arguments of this KP will accept macro register ID symbolic constants, as listed under “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.
Filled rectangle drawings are affected by the color, pixop, and style graphical properties. The color graphical property of the rectangle 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 rectangle 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 if the specified macro will be invoked with the retain property for later erasure).
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 rectangular area. The tiles are aligned to the absolute coordinates of the graphics display device, rather than the rectangle, so moving a viewer may change the relative alignment of the rectangle 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.
Purpose
Provides a mechanism to draw a filled rectangle in the context of a macro. The rectangle 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 rectangles are useful for coloring regions within an animated diagram, for alternatively representing model objects such as nodes, modules, and states, or for diagramming abstractions such as protocol layers or packet fields.
Errors
- Program Abort: segmentation violation (due to a badly formed string for the
pat_nameargument, if a pattern fill is specified by thepropsargument) - 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 argumentsx,y,width, orheightthat exceeds the range of a short)
Reference
- Use the KP op_anim_mgp_rect_draw() to draw a rectangle outline within a macro
- Use the KP op_anim_igp_rect_fill() to fill a rectangle 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