Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_Text interface uses an underlying font engine to render text. Currently, two font engines are supported: AG_FONT_VECTOR (for rendering any font supported by FreeType) and AG_FONT_BITMAP (for rendering simple pixmap fonts).

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_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_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, size_t len, const char *format, ...)

void (AG_TextPromptString, const char *prompt, void (*ok_fn)(AG_Event *), const char *fmt, ...)

AG_Window * AG_TextPromptOptions (AG_Button **buttons, Uint nButtons, 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.

The AG_TextPromptString() creates a modal dialog asking the user for a text string. Once the user confirms the entry, the ok_fn() callback is invoked (see AG_Event(3) for details on the argument format). The entered string is the last argument on the stack.

AG_TextPromptOptions() creates a dialog displaying a text string and an array of buttons. buttons is a set of existing AG_Button(3) widgets to display.

FONT SELECTION

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

void AG_DestroyFont (AG_Font *font)

void AG_SetDefaultFont (AG_Font *font)

void AG_SetRTL (int enable)

void AG_TextParseFontSpec (const char *fontspec)

The AG_FetchFont() function retrieves the specified font face, loading it from file if it's not currently resident. If face is NULL, the default font.face configuration setting is used (see AG_Config(3)). The font file should reside in one of the directories specified in font-path setting. The size argument is specified in points (if -1 is passed, the default configuration setting font.size is used). If flags is -1, the default configuration setting font.flags is used. The function returns a pointer to the font object, or NULL if an error occured.

The AG_DestroyFont() function releases a font object assuming it is no longer in use.

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.