op_anim_macro_destroy()
Abstract
Removes the specified macro, releasing its memory and removing all retained drawings created via invocations of the macro.
Syntax
op_anim_macro_destroy (anmid)
| Argument | Type | Description |
|---|---|---|
anmid |
Anmid |
macro ID [An animation macro ID can be obtained when a macro is created via the KP op_anim_macro_create().] |
Return Type
void
no return value
Example
/* Determine interrupt type. */
itype = op_intrpt_type ();
/* Check for node failure interrupt. */
if (itype = OPC_INTRPT_FAIL)
{
/* Node is dead; close associated animation viewer and macro’s. */
op_anim_viewer_close (local_vid);
op_anim_macro_destroy (local_move_mid);
op_anim_macro_destroy (local_comm_mid);
}
Details
Retained drawings created by the destroyed macro are removed from viewer retained drawing lists, but their on-screen manifestations are not explicitly erased (these can be made to disappear by issuing a viewer redraw request).
Purpose
Provides a mechanism for destroying an existing macro. This is rarely necessary, since macros are typically not numerous, small in resource usage, and sharable by multiple viewers. However, if a large sequence of disposable macros is to be defined, it may be necessary to enforce a birth-death cycle for macros using this KP.
Errors
- Recoverable Error: Animation macro ID (
<anmid>) is [out-of-range | unrecognized]. (former case due to invalidanmidargument value; latter case to destroyed macro)
Reference
- Use the KP op_anim_macro_close() to complete a macro definition, prohibiting the addition of further requests
- Use the KP op_anim_viewer_close() to close a viewer (this will not affect the macro definitions which were displayed in the viewer)