op_anim_mgp_bg_fill()
Abstract
Adds a primitive to the specified macro that fills in a viewer’s window with a background color or pattern.
Syntax
op_anim_mgp_bg_fill (anmid, props, pat_name)
| 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 [This string indicates the icon to be used as a pattern for the fill operation (this argument is only referenced if the property flag OPC_ANIM_STYLE_PATTERN is specified. The fill icon must be loaded by op_vuanim. User-defined icons can be added to a user’s icon database user_icon_db in $HOME/op_admin.)] |
Return Type
void
no return value
Example
/** Construct a macro which draws viewer title frame; **/
/** the title is expected in register S. **/
mid = op_anim_macro_create ("vtframe");
/* Fill the background with low-key color. */
op_anim_mgp_bg_fill (mid, OPC_ANIM_COLOR_TAN, " ");
/* Draw a double-rectangle inside window. */
op_anim_mgp_rect_draw (mid, OPC_ANIM_COLOR_BLACK, 10, 10, 600, 500);
op_anim_mgp_rect_draw (mid, OPC_ANIM_COLOR_BLACK, 12, 12, 596, 496);
/* Draw title near top of rectangle. */
op_anim_mgp_text_draw (mid, OPC_ANIM_ALIGNH_CENTER | OPC_ANIM_ALIGNV_TOP |
OPC_ANIM_FONT_OPEN_18 | OPC_ANIM_COLOR_BLACK, 300, 20, OPC_ANIM_REG_S_STR);
op_anim_macro_close (mid);
Details
The props and pat_name 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.
Background fills are affected by the color, pixop, and style graphical properties. Note that the color of the background fill is set by the color graphical property, rather than the bgcolor graphical property (bgcolor is used only for the background color of text drawing). The default color is black. If the pixop graphical property is set to a value other than the default (OPC_ANIM_PIXOP_SRC), the background fill may merge in with any graphical figures displayed in the viewer, rather than replacing them (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 whole viewer window. The tiles are aligned to the absolute coordinates of the graphics display device, rather than the viewer, so moving a viewer may change the relative alignment of its pattern background with any other graphical figures displayed in the viewer. 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 set a particular color as the background for a viewer window in the context of a macro (the default background color of newly created viewers is black). This can be useful for special information displays in which a color background can enhance the presentation. Filling the whole viewer window is also an easy way to get the viewer back to a known state before preceding with subsequent animation requests.
Errors
- Program Abort: segmentation violation (due to a badly formed literal 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)
Reference
- Use the KP op_anim_mgp_rect_fill() to fill a rectangular viewer region within a macro
- Use the KP op_anim_igp_bg_fill() to fill the viewer window background 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