<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_Text interface enables Agar applications to size and render text. Currently, two font engines are supported: AG_FONT_VECTOR (using FreeType) and AG_FONT_BITMAP (simple built-in bitmap font renderer).

RENDER SETTINGS

A number of settings which affect the rendering functions (see RENDERING section) can be modified at any time, and are organized in a stack of rendering attributes.

void AG_PushTextState (void)

void AG_PopTextState (void)

void AG_TextFont (AG_Font *font)

AG_Font * AG_TextFontLookup (const char *face, int size, Uint flags)

AG_Font * AG_TextFontPct (int size_pct)

AG_Font * AG_TextFontPts (int points)

void AG_TextJustify (enum ag_text_justify mode)

void AG_TextValign (enum ag_text_valign mode)

void AG_TextTabWidth (int pixels)

void AG_TextColor (AG_Color C)

void AG_TextColorRGB (Uint8 r, Uint8 g, Uint8 b)

void AG_TextColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

void AG_TextBGColor (AG_Color C)

void AG_TextBGColorRGB (Uint8 r, Uint8 g, Uint8 b)

void AG_TextBGColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

void AG_TextBGColorRGBA (Uint8 r, Uint8 g, Uint8 b, Uint8 a)

The AG_PushTextState() and AG_PopTextState() functions respectively push and pop the text rendering attribute stack. The attribute stack can hold AG_TEXT_STATES_MAX items (at least 32).

The AG_TextFont() function selects font as the active font.

AG_TextFontLookup() searches the font cache for the given font face, size and flags combination, possibly loading new fonts from disk (scanning all font-path directories). On success, the font is selected as the active font and returned. If no match is found, the function returns NULL.

AG_TextFontPts() sets the size of the active font in points.

AG_TextFontPct() sets the size of the active font, specified as percentage of current font size. An argument of 100% leaves the size unchanged.

AG_TextJustify() selects the justification mode to use in multi-line rendering:

enum ag_text_justify {
	AG_TEXT_LEFT,
	AG_TEXT_CENTER,
	AG_TEXT_RIGHT
};

AG_TextValign() selects the vertical alignment mode to use where text is rendered to an area of arbitrary height:

enum ag_text_valign {
	AG_TEXT_TOP,
	AG_TEXT_MIDDLE,
	AG_TEXT_BOTTOM
};

AG_TextTabWidth() sets the width of tabs in pixels.

AG_TextColor() sets the text color (see AG_Color(3)). AG_TextColorRGB() and AG_TextColorRGBA() accept individual color components.

Similarly, AG_TextBG*() functions assign a background color for the surfaces returned by the rendering functions.

RENDERING

AG_Surface * AG_TextRender (const char *text)

AG_Surface * AG_TextRenderUCS4 (const Uint32 *text)

AG_Surface * AG_TextRenderf (const char *fmt, ...)

AG_Glyph * AG_TextRenderGlyph (Uint32 uch)

void AG_TextSize (const char *text, int *w, int *h)

void AG_TextSizeUCS4 (const Uint32 *text, int *w, int *h)

void AG_TextSizeMulti (const char *text, int *w, int *h, Uint **wLines, Uint *nLines)

void AG_TextSizeMultiUCS4 (const Uint32 *text, int *w, int *h, Uint **wLines, Uint *nLines)

The AG_TextRender() function renders text to a new, transparent surface. The input text may contain UTF-8 sequences. The AG_TextRenderf() variant accepts printf(3) style arguments.

AG_TextRenderUCS4() renders text in UCS-4 format onto a new surface. AG_TextRenderGlyph() renders the specified UCS-4 encoded Unicode character. The function returns an AG_Glyph structure, which has the following public (read-only) members:

Uint32 ch	Unicode character (UCS-4 encoded)
AG_Surface *su	Pixel surface
Uint texture	OpenGL texture handle (if OpenGL is in use)
float texcoord[4]	OpenGL texture coordinates (if OpenGL is in use
int advance	Amount of translation (in pixels) recommended to follow when rendering text

The AG_TextSize() and AG_TextSizeUCS4() functions return the minimal bounding box in pixels required for rendering the given text. The AG_TextSizeMulti() and AG_TextSizeMultiUCS4() variants also return the number of lines into nLines and the width in pixels of each line in the array wLines (which must be initialized to NULL).

CANNED DIALOGS

void AG_TextMsg (enum ag_text_msg_title title, const char *format, ...)

void AG_TextMsgS (enum ag_text_msg_title title, const char *msg)

void AG_TextMsgFromError (void)

void AG_TextWarning (const char *disableKey, const char *format, ...)

void AG_TextWarningS (const char *disableKey, const char *msg)

void AG_TextError (const char *format, ...)

void AG_TextErrorS (const char *msg)

void AG_TextInfo (const char *disableKey, const char *format, ...)

void AG_TextInfoS (const char *disableKey, const char *msg)

void AG_TextTmsg (enum ag_text_msg_title title, Uint32 expire, const char *format, ...)

void AG_TextTmsgS (enum ag_text_msg_title title, Uint32 expire, const char *msg)

void AG_TextEditFloat (double *fp, double min, double max, const AG_Unit *unit, const char *format, ...)

void AG_TextEditString (char *buf, AG_Size len, const char *format, ...)

The AG_TextMsg() function displays a text message window containing the given printf(3) formatted string, and an OK button. title is one of the following:

enum ag_text_msg_title {
	AG_MSG_ERROR,
	AG_MSG_WARNING,
	AG_MSG_INFO
};

AG_TextMsgFromError() displays a standard error message using the value of AG_GetError(3).

AG_TextWarning() displays a standard warning message, but also provides the user with a Don't show again checkbox. The checkbox controls the AG_Config(3) value specified by disableKey.

AG_TextError() displays an error message. It is equivalent to AG_TextMsg() with a AG_MSG_ERROR setting.

AG_TextInfo() displays an informational message. Similar to AG_TextWarning(), a Don't show again option is provided to the user (and the setting is referenced by disableKey).

The AG_TextTmsg() routine is a variant of AG_TextMsg() which displays the message for a specific amount of time, given in milliseconds.

The AG_TextEditFloat() function displays a dialog asking for a floating-point value. The fp argument is a pointer to the variable, while min and max define the acceptable range. Unless unit is NULL, the argument indicates the unit system to use (as in AG_Units(3)).

Similarly, AG_TextEditString() displays a dialog asking for a string, where buf is a pointer to the string buffer, and len is the size of the buffer.

FONT SELECTION

AG_Font * AG_FetchFont (const char *face, int size, Uint flags)

void AG_UnusedFont (AG_Font *font)

void AG_SetDefaultFont (AG_Font *font)

void AG_SetRTL (int enable)

void AG_TextParseFontSpec (const char *fontspec)

AG_FetchFont() loads (or retrieves from cache) the font corresponding to the specified face and size in points. Recognized flags include AG_FONT_BOLD and AG_FONT_ITALIC. The font is loaded from file if not currently resident (unless the fontconfig library is available, the font file should reside in one of the directories specified in the font-path setting). If face is NULL or size is -1, the AG_Config(3) defaults "font.face" and "font.size" are used. AG_FetchFont() returns a pointer to the font object, incrementing its reference count. If the font cannot be loaded, the function returns NULL.

The AG_UnusedFont() function decrements the reference count on a font. If the font is no longer referenced, it is destroyed.

AG_SetDefaultFont() sets the specified font object as the default font.

AG_SetRTL() enables or disables right-to-left text mode.

The AG_TextParseFontSpec() function parses a font specification of the form face,size,style (valid separators include :,./) and assigns the default font. This function is typically called prior to AG_InitGraphics() (e.g., to parse alternate fonts specified on the command line).

HISTORY

The AG_Text interface first appeared in Agar 1.0. The stack of rendering attributes was added in Agar 1.3. Right-to-left rendering first appeared in Agar 1.4.1.