op_anim_igp_macro_draw()
Abstract
Invokes a macro with a list of register assignments, producing a drawing within the specified viewer.
Syntax
op_anim_igp_macro _draw (anvid, props, anmid, [ regid, regval, ]… OPC_EOL)
| Argument | Type | Description |
|---|---|---|
anvid |
Anvid |
viewer ID [This value is a numeric identifier which references a viewer. The macro will be invoked in the context of 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.] |
anmid |
Anmid |
macro ID [This value is a numeric identifier which references the macro to be invoked.] |
regid |
int |
drawing register ID [This value is a numeric code which identifies a specific macro register to be assigned.] |
regval |
void* |
value for assignment to macro register |
Return Type
Andid
drawing ID of macro invocation
[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
/* Create a macro which draws a line between two nodes. */
mid = op_anim_macro_create ("node dynconn");
/* Determine the positions of the nodes A & B; the position of A is */
/* stored in (M,N) and the position of B is stored in (O,P). */
op_anim_mme_nobj_pos (mid, OPC_ANIM_OBJTYPE_NODE, OPC_ANIM_REG_A_STR,
OPC_ANIM_REG_M_INT, OPC_ANIM_REG_N_INT, OPC_ANIM_VERTEX_ICON_CTR);
op_anim_mme_nobj_pos (mid, OPC_ANIM_OBJTYPE_NODE, OPC_ANIM_REG_B_STR,
OPC_ANIM_REG_O_INT, OPC_ANIM_REG_P_INT, OPC_ANIM_VERTEX_ICON_CTR);
/* Draw the line between the nodes. */
op_anim_mgp_line_draw (mid, OPC_ANIM_COLOR_GREEN,
OPC_ANIM_REG_M_INT, OPC_ANIM_REG_N_INT, OPC_ANIM_REG_O_INT, OPC_ANIM_REG_P_INT);
/* Execute the macro for source & destination nodes. */
op_anim_igp_macro_draw (vid, OPC_ANIM_RETAIN, mid,
OPC_ANIM_REG_A_STR, src_nd_name,
OPC_ANIM_REG_B_STR, dst_nd_name, OPC_EOL);
Details
The arguments to this KP include a list of zero or more register assignments. Each register assignment is represented by a pair of adjacent arguments (regid and regval), and the list is terminated by the symbolic constant OPC_EOL (“End-Of-List”). The 26 macro registers named A-Z are identified by predefined symbolic constants listed under “Animation Macro Register Identifier Symbolic Constants—Integer Values“ on page 8. Because macro registers can hold integer, double, or string (char*) values, the regval arguments accept any of these types. The regval arguments are declared as void*, but their actual type must match that of the corresponding register ID.
Macro drawings are only affected by the retain graphical property. Macro 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. Macros are retained as a whole; op_anim_mgp… requests within macros do not have independent retention control, and do not accept the retain graphical property.
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 invoke a parameterized sequence of animation requests known as a macro. Macros encapsulate animation requests, allowing them to be dealt with as a single unit. This KP conveniently supports the execution of multiple animation requests from a single function call. However, this can also be done by placing op_anim_igp… KPs in a C function. The more important services provided by macros are:
- the ability to erase all requests of a macro by calling op_anim_igp_drawing_erase()
- the ability to update selected register values of a macro drawing by calling op_anim_igp_macro_redraw()
- the ability to obtain and use model object positions within a macro by calling op_anim_mme_nobj_pos()
Errors
- Program Abort: segmentation violation (due to incorrect data types for the
regidorregvalarguments) - Recoverable Error: Animation macro register ID (
<regid>) is invalid. Unable to continue animation flow. (due to an invalid value for aregidargument) - Diagnostic Error: Animation viewer ID (
<anvid>) is out-of-range. (due to an invalid value for theanvidargument) - Diagnostic Error: Animation macro ID (
<anmid>) is out-of-range. (due to an invalid value for theanmidargument)
Reference
- Use the KP op_anim_macro_create() to create a macro, and
op_anim_mgp…KPs to define it - Use the KP op_anim_igp_macro_redraw() to redraw a macro with new register assignments
- Use the KP op_anim_igp_drawing_erase() to erase and deallocate a retained macro drawing 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