Text output

allegro_404_char — Character used when Allegro cannot find a glyph.
font — A simple 8x8 fixed size font.
text_height — Returns the height of a font in pixels.
text_length — Returns the length of a string in pixels.
textout_centre_ex — Writes a centered string on a bitmap.
textout_ex — Writes a string on a bitmap.
textout_justify_ex — Draws justified text within a region.
textout_right_ex — Writes a right aligned string on a bitmap.
textprintf_centre_ex — Formatted centered output of a string.
textprintf_ex — Formatted output of a string.
textprintf_justify_ex — Formatted justified output of a string.
textprintf_right_ex — Formatted right aligned output of a string.

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.

See also: textout_ex, textprintf_ex.

Examples using this: Available Allegro examples.

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, `^', but you can change this global to use any other character instead. Example:

      /* Show unknown glyphs with an asterisk. */
      allegro_404_char = '*';

See also: font.

int text_length(const FONT *f, const char *str);

Returns the length (in pixels) of a string in the specified font. Example:

      int width = text_length(font, "I love spam");
      ...
      bmp = create_bitmap(width, height);

See also: text_height.

Examples using this: ex12bit, exmidi, expat, exunicod.

int text_height(const FONT *f)

Returns the height (in pixels) of the specified font. Example:

      int height = text_height(font);
      ...
      bmp = create_bitmap(width, height);

See also: text_length.

Examples using this: ex12bit, exmidi, expackf, expat, exsprite, exsyscur, exunicod.

void textout_ex(BITMAP *bmp, const FONT *f, const char *s, int x, int y, int color, int bg);

Writes the string `s' onto the bitmap at position x, y, using the specified font, foreground color and background color. If the background color is -1, then the text is written transparently. If the foreground 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. For high and true color fonts, the foreground color is ignored and always treated as -1. Example:

      /* Show the program's version in blue letters. */
      textout_ex(screen, font, "v4.2.0-beta2", 10, 10,
                 makecol(0, 0, 255), -1);

See also: font, textout_centre_ex, textout_right_ex, textout_justify_ex, textprintf_ex, text_height, text_length.

Examples using this: Available Allegro examples.

void textout_centre_ex(BITMAP *bmp, const FONT *f, const char *s, int x, y, int color, int bg);

Like textout_ex(), but interprets the x coordinate as the centre rather than the left edge of the string. Example:

      /* Important texts go in the middle. */
      width = text_length("GAME OVER");
      textout_centre_ex(screen, font, "GAME OVER",
                        SCREEN_W / 2, SCREEN_H / 2,
                        makecol(255, 0, 0), makecol(0, 0, 0));

See also: textout_ex, textprintf_centre_ex.

Examples using this: Available Allegro examples.

void textout_right_ex(BITMAP *bmp, const FONT *f, const char *s, int x, int y, int color, int bg);

Like textout_ex(), but interprets the x coordinate as the right rather than the left edge of the string. Example:

      textout_right_ex(screen, font, "Look at this color!",
                       SCREEN_W - 10, 10, my_yellow, -1);

See also: textout_ex, textprintf_right_ex.

void textout_justify_ex(BITMAP *bmp, const FONT *f, const char *s, int x1, int x2, int y, int diff, int color, int bg);

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. Example:

      char *lines[] = {"Draws justified text",
                       "within the specified",
                       "x2-x1 area. But not",
                       "T H I S !", NULL};
      /* Show the justification marker. */
      vline(screen, 200, 0, SCREEN_H-1, makecol(0, 0, 0));
      /* Draw all the lines until we reach a NULL entry. */
      for (num = 0, y = 0; lines[num]; num++, y += text_height(font))
         textout_justify_ex(screen, font, lines[num], 0, 200,
                            y, 80, makecol(0, 0, 0),
                            makecol(255, 255, 255));

See also: textout_ex, textprintf_justify_ex.

void textprintf_ex(BITMAP *bmp, const FONT *f, int x, int y, int color, int bg, const char *fmt, ...);

Formatted text output, using a printf() style format string. Due to an internal limitation, this function can't be used for extremely long texts. If you happen to reach this limit, you can work around it by using uszprintf() and textout_ex(), which don't have any. Example:

      int player_score;
      ...
      textprintf_ex(screen, font, 10, 10, makecol(255, 100, 200),
                    -1, "Score: %d", player_score);

See also: font, textout_ex, textprintf_centre_ex, textprintf_right_ex, textprintf_justify_ex, text_height, text_length, uszprintf.

Examples using this: Available Allegro examples.

void textprintf_centre_ex(BITMAP *bmp, const FONT *f, int x, int y, int color, int bg, const char *fmt, ...);

Like textprintf_ex(), but interprets the x coordinate as the centre rather than the left edge of the string. This function shares the text length limitation of textprintf_ex(). Example:

      textprintf_centre_ex(screen, font, SCREEN_W / 2, 120,
                           makecol(0, 100, 243), -1,
                           "Your best score so far was %d!",
                           total_max_points);

See also: textprintf_ex, textout_centre_ex.

Examples using this: Available Allegro examples.

void textprintf_right_ex(BITMAP *bmp, const FONT *f, int x, y, color, bg, const char *fmt, ...);

Like textprintf_ex(), but interprets the x coordinate as the right rather than the left edge of the string. This function shares the text length limitation of textprintf_ex(). Example:

      textprintf_right_ex(screen, font, SCREEN_W - 10, 10,
                          makecol(200, 200, 20), -1,
                          "%d bullets left", player_ammo);

See also: textprintf_ex, textout_right_ex.

Examples using this: exmouse.

void textprintf_justify_ex(BITMAP *bmp, const FONT *f, int x1, x2, y, diff, color, bg, const char *fmt, ...);

Like textout_justify_ex(), but using a printf() style format string. This function shares the text length limitation of textprintf_ex(). Example:

      char *lines[] = {"Line %02d: Draws justified text",
                       "Line %02d: within the specified",
                       "Line %02d: x2-x1 area. But not",
                       "Line %02d: T H I S !", NULL};
      /* Show the justification marker. */
      vline(screen, 300, 0, SCREEN_H-1, makecol(0, 0, 0));
      /* Draw all the lines until we reach a NULL entry. */
      for (num = 0, y = 0; lines[num]; num++, y += text_height(font))
         textprintf_justify_ex(screen, font, 0, 300, y, 180,
                               makecol(0, 0, 0), makecol(255, 255, 255),
                               lines[num], num);

See also: textprintf_ex, textout_justify_ex.

Back to contents