<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Text output
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Text output">Text output</a></h1>
<ul>
<li><a href="#allegro_404_char">allegro_404_char</a> — Character used when Allegro cannot find a glyph.
<li><a href="#font">font</a> — A simple 8x8 fixed size font.
<li><a href="#text_height">text_height</a> — Returns the height of a font in pixels.
<li><a href="#text_length">text_length</a> — Returns the length of a string in pixels.
<li><a href="#textout_centre_ex">textout_centre_ex</a> — Writes a centered string on a bitmap.
<li><a href="#textout_ex">textout_ex</a> — Writes a string on a bitmap.
<li><a href="#textout_justify_ex">textout_justify_ex</a> — Draws justified text within a region.
<li><a href="#textout_right_ex">textout_right_ex</a> — Writes a right aligned string on a bitmap.
<li><a href="#textprintf_centre_ex">textprintf_centre_ex</a> — Formatted centered output of a string.
<li><a href="#textprintf_ex">textprintf_ex</a> — Formatted output of a string.
<li><a href="#textprintf_justify_ex">textprintf_justify_ex</a> — Formatted justified output of a string.
<li><a href="#textprintf_right_ex">textprintf_right_ex</a> — Formatted right aligned output of a string.
</ul>
<p>
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 <a href="grabber.html">grabber.txt</a> 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.
<p><br>
<div class="al-api"><b>extern <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *<a name="font">font</a>;</b></div><br>
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.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textout_ex" title="Writes a string on a bitmap.">textout_ex</a>,
<a class="xref" href="#textprintf_ex" title="Formatted output of a string.">textprintf_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>extern int <a name="allegro_404_char">allegro_404_char</a>;</b></div><br>
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, <tt>`^'</tt>, but you can change this global to use any other
character instead. Example:
<blockquote class="code"><pre>
/* Show unknown glyphs with an asterisk. */
<a href="#allegro_404_char" class="autotype" title="Character used when Allegro cannot find a glyph.">allegro_404_char</a> = '*';</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#font" title="A simple 8x8 fixed size font.">font</a>.</blockquote>
<div class="al-api"><b>int <a name="text_length">text_length</a>(const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, const char *str);</b></div><br>
Returns the length (in pixels) of a string in the specified font. Example:
<blockquote class="code"><pre>
int width = <a href="#text_length" class="autotype" title="Returns the length of a string in pixels.">text_length</a>(<a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, "I love spam");
...
bmp = <a href="alleg009.html#create_bitmap" class="autotype" title="Creates a memory bitmap.">create_bitmap</a>(width, height);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#text_height" title="Returns the height of a font in pixels.">text_height</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex12bit" title="How to fake a 12-bit truecolor mode on an 8-bit card.">ex12bit</a>,
<a class="eref" href="alleg045.html#exmidi" title="Playing MIDI music.">exmidi</a>,
<a class="eref" href="alleg045.html#expat" title="Using patterned drawing modes and sub-bitmaps.">expat</a>,
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>int <a name="text_height">text_height</a>(const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f)</b></div><br>
Returns the height (in pixels) of the specified font. Example:
<blockquote class="code"><pre>
int height = <a href="#text_height" class="autotype" title="Returns the height of a font in pixels.">text_height</a>(<a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>);
...
bmp = <a href="alleg009.html#create_bitmap" class="autotype" title="Creates a memory bitmap.">create_bitmap</a>(width, height);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#text_length" title="Returns the length of a string in pixels.">text_length</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex12bit" title="How to fake a 12-bit truecolor mode on an 8-bit card.">ex12bit</a>,
<a class="eref" href="alleg045.html#exmidi" title="Playing MIDI music.">exmidi</a>,
<a class="eref" href="alleg045.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>,
<a class="eref" href="alleg045.html#expat" title="Using patterned drawing modes and sub-bitmaps.">expat</a>,
<a class="eref" href="alleg045.html#exsprite" title="Datafiles access and sprite animation.">exsprite</a>,
<a class="eref" href="alleg045.html#exsyscur" title="Hardware accelerated mouse cursors.">exsyscur</a>,
<a class="eref" href="alleg045.html#exunicod" title="Using Unicode string functions.">exunicod</a>.</blockquote>
<div class="al-api"><b>void <a name="textout_ex">textout_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, const char *s,
int x, int y, int color, int bg);</b></div><br>
Writes the string <tt>`s'</tt> 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:
<blockquote class="code"><pre>
/* Show the program's version in blue letters. */
<a href="#textout_ex" class="autotype" title="Writes a string on a bitmap.">textout_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, "v4.2.0-beta2", 10, 10,
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 255), -1);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#font" title="A simple 8x8 fixed size font.">font</a>,
<a class="xref" href="#textout_centre_ex" title="Writes a centered string on a bitmap.">textout_centre_ex</a>,
<a class="xref" href="#textout_right_ex" title="Writes a right aligned string on a bitmap.">textout_right_ex</a>,
<a class="xref" href="#textout_justify_ex" title="Draws justified text within a region.">textout_justify_ex</a>,
<a class="xref" href="#textprintf_ex" title="Formatted output of a string.">textprintf_ex</a>,
<a class="xref" href="#text_height" title="Returns the height of a font in pixels.">text_height</a>,
<a class="xref" href="#text_length" title="Returns the length of a string in pixels.">text_length</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>void <a name="textout_centre_ex">textout_centre_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, const char *s,
int x, y, int color, int bg);</b></div><br>
Like textout_ex(), but interprets the x coordinate as the centre rather
than the left edge of the string. Example:
<blockquote class="code"><pre>
/* Important texts go in the middle. */
width = <a href="#text_length" class="autotype" title="Returns the length of a string in pixels.">text_length</a>("GAME OVER");
<a href="#textout_centre_ex" class="autotype" title="Writes a centered string on a bitmap.">textout_centre_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, "GAME OVER",
<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a> / 2, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a> / 2,
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(255, 0, 0), <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 0));</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textout_ex" title="Writes a string on a bitmap.">textout_ex</a>,
<a class="xref" href="#textprintf_centre_ex" title="Formatted centered output of a string.">textprintf_centre_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>void <a name="textout_right_ex">textout_right_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, const char *s,
int x, int y, int color, int bg);</b></div><br>
Like textout_ex(), but interprets the x coordinate as the right rather
than the left edge of the string. Example:
<blockquote class="code"><pre>
<a href="#textout_right_ex" class="autotype" title="Writes a right aligned string on a bitmap.">textout_right_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, "Look at this color!",
<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a> - 10, 10, my_yellow, -1);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textout_ex" title="Writes a string on a bitmap.">textout_ex</a>,
<a class="xref" href="#textprintf_right_ex" title="Formatted right aligned output of a string.">textprintf_right_ex</a>.</blockquote>
<div class="al-api"><b>void <a name="textout_justify_ex">textout_justify_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, const char *s,
int x1, int x2, int y, int diff, int color,
int bg);</b></div><br>
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:
<blockquote class="code"><pre>
char *lines[] = {"Draws justified text",
"within the specified",
"x2-x1 area. But not",
"T H I S !", NULL};
/* Show the justification marker. */
<a href="alleg013.html#vline" class="autotype" title="Draws a vertical line onto the bitmap.">vline</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, 200, 0, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>-1, <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 0));
/* Draw all the lines until we reach a NULL entry. */
for (num = 0, y = 0; lines[num]; num++, y += <a href="#text_height" class="autotype" title="Returns the height of a font in pixels.">text_height</a>(<a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>))
<a href="#textout_justify_ex" class="autotype" title="Draws justified text within a region.">textout_justify_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, lines[num], 0, 200,
y, 80, <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 0),
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(255, 255, 255));</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textout_ex" title="Writes a string on a bitmap.">textout_ex</a>,
<a class="xref" href="#textprintf_justify_ex" title="Formatted justified output of a string.">textprintf_justify_ex</a>.</blockquote>
<div class="al-api"><b>void <a name="textprintf_ex">textprintf_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, int x, int y,
int color, int bg, const char *fmt, ...);</b></div><br>
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:
<blockquote class="code"><pre>
int player_score;
...
<a href="#textprintf_ex" class="autotype" title="Formatted output of a string.">textprintf_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, 10, 10, <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(255, 100, 200),
-1, "Score: %d", player_score);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#font" title="A simple 8x8 fixed size font.">font</a>,
<a class="xref" href="#textout_ex" title="Writes a string on a bitmap.">textout_ex</a>,
<a class="xref" href="#textprintf_centre_ex" title="Formatted centered output of a string.">textprintf_centre_ex</a>,
<a class="xref" href="#textprintf_right_ex" title="Formatted right aligned output of a string.">textprintf_right_ex</a>,
<a class="xref" href="#textprintf_justify_ex" title="Formatted justified output of a string.">textprintf_justify_ex</a>,
<a class="xref" href="#text_height" title="Returns the height of a font in pixels.">text_height</a>,
<a class="xref" href="#text_length" title="Returns the length of a string in pixels.">text_length</a>,
<a class="xref" href="alleg002.html#uszprintf" title="Writes formatted data into a buffer, specifying size.">uszprintf</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>void <a name="textprintf_centre_ex">textprintf_centre_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, int x, int y,
int color, int bg, const char *fmt, ...);</b></div><br>
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:
<blockquote class="code"><pre>
<a href="#textprintf_centre_ex" class="autotype" title="Formatted centered output of a string.">textprintf_centre_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, <a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a> / 2, 120,
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 100, 243), -1,
"Your best score so far was %d!",
total_max_points);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textprintf_ex" title="Formatted output of a string.">textprintf_ex</a>,
<a class="xref" href="#textout_centre_ex" title="Writes a centered string on a bitmap.">textout_centre_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>void <a name="textprintf_right_ex">textprintf_right_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, int x, y, color, bg,
const char *fmt, ...);</b></div><br>
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:
<blockquote class="code"><pre>
<a href="#textprintf_right_ex" class="autotype" title="Formatted right aligned output of a string.">textprintf_right_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, <a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a> - 10, 10,
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(200, 200, 20), -1,
"%d bullets left", player_ammo);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textprintf_ex" title="Formatted output of a string.">textprintf_ex</a>,
<a class="xref" href="#textout_right_ex" title="Writes a right aligned string on a bitmap.">textout_right_ex</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exmouse" title="Getting input from the mouse.">exmouse</a>.</blockquote>
<div class="al-api"><b>void <a name="textprintf_justify_ex">textprintf_justify_ex</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bmp, const <a class="autotype" href="alleg001.html#FONT" title="Stores an Allegro font.">FONT</a> *f, int x1, x2, y,
diff, color, bg, const char *fmt, ...);</b></div><br>
Like textout_justify_ex(), but using a printf() style format string. This
function shares the text length limitation of textprintf_ex(). Example:
<blockquote class="code"><pre>
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. */
<a href="alleg013.html#vline" class="autotype" title="Draws a vertical line onto the bitmap.">vline</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, 300, 0, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>-1, <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 0));
/* Draw all the lines until we reach a NULL entry. */
for (num = 0, y = 0; lines[num]; num++, y += <a href="#text_height" class="autotype" title="Returns the height of a font in pixels.">text_height</a>(<a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>))
<a href="#textprintf_justify_ex" class="autotype" title="Formatted justified output of a string.">textprintf_justify_ex</a>(<a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a>, <a href="#font" class="autotype" title="A simple 8x8 fixed size font.">font</a>, 0, 300, y, 180,
<a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(0, 0, 0), <a href="alleg012.html#makecol" class="autotype" title="Converts an RGB value into the current pixel format.">makecol</a>(255, 255, 255),
lines[num], num);</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#textprintf_ex" title="Formatted output of a string.">textprintf_ex</a>,
<a class="xref" href="#textout_justify_ex" title="Draws justified text within a region.">textout_justify_ex</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
x86_64
>
media
>
main
>
by-pkgid
>
c13bc007afe382f898b3b1cfcaf62e82
>
files
>
791
