VgaGames 3 - Miscellaneous man-pages

[.. upper level ..]

VG3_text_with_images()

[added in version 1.2]

Create an image containing text and images.
SYNTAX
void * VG3_text_with_images(void *wstruct, struct vg3_text *stxt, const char *imgpath, int fcolor, int bcolor)

FUNCTION PARAMETERS
wstruct Window-struct
stxt Text with formatting entries
imgpath (Relative) path to images to load
fcolor Foreground color (from VGAG3_COLORS or VGAG3_COLOR_CUSTOM)
bcolor Background color (from VGAG3_COLORS or VGAG3_COLOR_CUSTOM)

RETURN VALUE
Returns a created image or NULL on failure.

ERRORS
On error VG3_errmsg() returns: EINVAL - error in argument ENOSYS - cannot create image ENOMEM - cannot get memory ENOENT - error loading fontfile

DESCRIPTION
Create an image containing text and images. The text in stxt must contain formatting entries to arrange the contents. All text between the formatting entries will be arranged into text boxes, where each newline creates a new line in this box. The boxes will be placed from left to right until a formatting newline is found. Formatting is done via %[<entry>]. <entry> can be as following: - IMG: followed by a image file to load (with path) Load and insert an image into corresponding position (e.g. %[IMG:images/image1.bmp]) - NL: followd by LEFT or MIDDLE or RIGHT A formatting newline, that means the next boxes will be placed benath the previous boxes and will be arranged left-orientated, centered or right-orientated (e.g. %[NL:LEFT]) - SPACE: followd by an integer specifying the number of spaces A spacing box, which will put text spaces between two adjoining boxes - BOLD Effective only for boxes containing text, all following text boxes will be set to bold (if possible) Reset it with NORMAL - NORMAL Effective only for boxes containing text, all following text boxes will be set back to the foreground color - COLOR: followed by three integers separated by colon: <red>,<green>,<blue> Effective only for boxes containing text, all following text boxes will be set to the specified color (e.g. %[COLOR:128,128,0]) Reset it with NORMAL - FONTFILE: followed by a font name, e.g. 10x17.font Effective only for boxes containing text, all following text boxes will be drawn with the specified font, if the font name is empty, the font will be set back to the font given in stxt (e.g. %[FONTFILE:8x8.font] or %[FONTFILE:]) One newline before and behind the formatting entries will be discarded, so it is not necessary to put the entries directly between the text.

EXAMPLE

A text just containing a header line,
then side by side a text box, an image, another text box,
then benath a footer line
%[NL:MIDDLE]
%[FONTFILE:10x17.font]The header%[FONTFILE:]
%[NL:LEFT]
%[NL:LEFT]
First text box,
it consists of
three lines
%[SPACE:1]
%[IMG:images/image1.bmp]
%[SPACE:1]
Second text box
%[NL:LEFT]
%[NL:MIDDLE]
The footer

SEE ALSO
VG3_draw_text() VG3_draw_textline() VG3_output_text()