# Text output

####
- font
- allegro_404_char
- text_mode
- textout
- textout_centre
- textout_right
- textout_justify
- textprintf
- textprintf_centre
- textprintf_right
- textprintf_justify
- text_length
- text_height
- destroy_font

Allegro provides text output routines that work with both monochrome and color fonts, which can contain any number of Unicode character ranges. The grabber program can create fonts from sets of characters drawn in a bitmap file (see grabber.txt for more information), and can also import GRX or BIOS format font files. The font structure contains a number of hooks that can be used to extend it with your own custom drawing code: see the definition in allegro/text.h for details.

extern FONT *font;
A simple 8x8 fixed size font (the mode 13h BIOS default). If you want to alter the font used by the GUI routines, change this to point to one of your own fonts. This font contains the standard ASCII (U+20 to U+7F), Latin-1 (U+A1 to U+FF), and Latin Extended-A (U+0100 to U+017F) character ranges.

extern int allegro_404_char;
When Allegro cannot find a glyph it needs in a font, it will instead output the character given in allegro_404_char. By default, this is set to the caret symbol, '^'.

int text_mode(int mode);
Sets the mode in which text will be drawn. Returns previous mode. If mode is zero or positive, text output will be opaque and the background of the characters will be set to color #mode. If mode is negative, text will be drawn transparently (ie. the background of the characters will not be altered). The default is a mode of zero.

void textout(BITMAP *bmp, const FONT *f, const char *s, int x, y, int color);
Writes the string s onto the bitmap at position x, y, using the current text mode and the specified font and foreground color. If the color is -1 and a color font is in use, it will be drawn using the colors from the original font bitmap (the one you imported into the grabber program), which allows multicolored text output.

void textout_centre(BITMAP *bmp, const FONT *f, const char *s, int x, y, color);
Like textout(), but interprets the x coordinate as the centre rather than the left edge of the string.

void textout_right(BITMAP *bmp, const FONT *f, const char *s, int x, y, color);
Like textout(), but interprets the x coordinate as the right rather than the left edge of the string.

void textout_justify(BITMAP *bmp, const FONT *f, const char *s, int x1, int x2, int y, int diff, int color);
Draws justified text within the region x1-x2. If the amount of spare space is greater than the diff value, it will give up and draw regular left justified text instead.

void textprintf(BITMAP *bmp, const FONT *f, int x, y, color, const char *fmt, ...);
Formatted text output, using a printf() style format string.

void textprintf_centre(BITMAP *bmp, const FONT *f, int x, y, color, const char *fmt, ...);
Like textprintf(), but interprets the x coordinate as the centre rather than the left edge of the string.

void textprintf_right(BITMAP *bmp, const FONT *f, int x, y, color, const char *fmt, ...);
Like textprintf(), but interprets the x coordinate as the right rather than the left edge of the string.

void textprintf_justify(BITMAP *bmp, const FONT *f, int x1, int x2, int y, int diff, int color, const char *fmt, ...);
Like textout_justify, but using a printf() style format string.

int text_length(const FONT *f, const char *str);
Returns the length (in pixels) of a string in the specified font.

int text_height(const FONT *f)
Returns the height (in pixels) of the specified font.

void destroy_font(FONT *f);
Frees the memory being used by a font structure.

Back to Contents