<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

The AG_Text interface allows Agar GUI widgets to render text using a vector or a bitmap engine. FreeType is used by default if it is available.

RENDERING ATTRIBUTES

Agar maintains a stack of rendering attributes which influence the operation of text rendering and sizing routines. Attributes are set using functions such as AG_TextFont() or AG_TextColor().

Note: The functions below are *not* free-threaded and are only safe to invoke from the draw(), size_request(), size_allocate(), or any event handler of an AG_Widget(3) with the AG_WIDGET_USE_TEXT flag set.

void AG_PushTextState (void)

void AG_CopyTextState (AG_TextState *dst)

void AG_PopTextState (void)

AG_TextState * AG_TEXT_STATE_CUR (void)

void AG_TextFont (AG_Font *font)

AG_Font * AG_TextFontLookup (const char *face, float points, Uint flags)

AG_Font * AG_TextFontPct (int size_pct)

AG_Font * AG_TextFontPctFlags (int size_pct, Uint flags)

AG_Font * AG_TextFontPts (float size)

void AG_TextJustify (enum ag_text_justify mode)

void AG_TextValign (enum ag_text_valign mode)

void AG_TextTabWidth (int pixels)

void AG_TextColor (const 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 (const 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)

void AG_TextColorANSI (enum ag_ansi_color which, const AG_Color *c)

AG_PushTextState() increments the attribute stack pointer and creates a copy of the previous state in the current state. AG_PopTextState() decrements the stack pointer, discarding the current state. AG_CopyTextState() copies the current text state to dst. The text state stack can hold up to AG_TEXT_STATES_MAX elements.

The AG_TEXT_STATE_CUR() macro expands to an expression returning the pointer to the current AG_TextState. In debug mode, an additional validity test is performed.

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

AG_TextFontLookup() checks the font cache for a given combination of face, point size and flags, possibly loading new fonts from disk. On success, the font is set as the active font for the current text state and a pointer to it is returned. If no font was found, AG_TextFontLookup() returns NULL.

AG_TextFontPts() sets the size of the active font in points. If the argument nears 0.0 (is smaller than AG_FONT_PTS_EPSILON) then the AG_Config(3) default "font.size" is used.

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_TextFontPctFlags() allows an alternate font style via flags argument.

AG_TextJustify() selects the justify 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.

AG_TextColorANSI() modifies an entry in the 4-bit ANSI color palette. Subsequent calls to AG_TextRender() will display text containing AG_SGR_FG* or AG_SGR_BG* sequences in the specified color (until AG_PopTextState() is called). When the ANSI color palette is first modified, it is copied to the active AG_TextState in a copy-on-write fashion.

RENDERING

AG_Surface * AG_TextRender (const char *text)

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

AG_Surface * AG_TextRenderInternal (const AG_Char *text, const AG_Font *font, const AG_Color *cBg, const AG_Color *cFg)

AG_Glyph * AG_TextRenderGlyph (AG_Driver *drv, const AG_Font *font, const AG_Color *cBg, const AG_Color *cFg, AG_Char ch)

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

void AG_TextSizeInternal (const AG_Char *text, int *w, int *h)

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

void AG_TextSizeMultiInternal (const AG_Char *text, int *w, int *h, Uint **wLines, Uint *nLines)

AG_TextRender() renders the C string text onto a newly-allocated surface. The font, colors and spacings are according to the current Rendering Attributes. The input text may contain UTF-8 characters and ANSI SGR sequences.

AG_TextRenderInternal() renders onto a new surface text in native AG_Char encoding (which is either an ASCII char, or a 32-bit UCS-4 character in Unicode builds). AG_TextRenderGlyph() returns a pointer to the corresponding AG_Glyph from the cache, which has the following public (read-only) members:

AG_Char ch	Native character (UCS-4 or ASCII)
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_TextSizeInternal() functions return the minimal bounding box in pixels required for rendering the given text. The AG_TextSizeMulti() and AG_TextSizeMultiInternal() 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)

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 if disableKey is non-NULL, it 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(), if disableKey is non-NULL then a Don't show again option is also provided to the user.

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

FONT SELECTION

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

void AG_UnusedFont (AG_Font *font)

AG_Font * AG_SetDefaultFont (AG_Font *font)

void AG_TextParseFontSpec (const char *fontspec)

AG_FetchFont() loads (or retrieves from cache) the font corresponding to the specified face, size and flags attributes. Face may refer to either a system-wide font or a file in font-path. size is in points (fractional sizes are permitted). Possible flags include:

#define AG_FONT_BOLD           0x001    /* Bold style */
#define AG_FONT_ITALIC         0x002    /* Italic style */
#define AG_FONT_UNDERLINE      0x004    /* Generate underline */
#define AG_FONT_UPPERCASE      0x008    /* Force uppercase */
#define AG_FONT_OBLIQUE        0x010    /* Oblique style */
#define AG_FONT_UPRIGHT_ITALIC 0x020    /* Upright italic style */
#define AG_FONT_SEMICONDENSED  0x040    /* Semi-condensed */
#define AG_FONT_CONDENSED      0x080    /* Condensed */
#define AG_FONT_SW_BOLD        0x100    /* Software-generated bold */
#define AG_FONT_SW_OBLIQUE     0x200    /* Software-generated oblique */
#define AG_FONT_SW_ITALIC      AG_FONT_SW_OBLIQUE

#define AG_FONT_WEIGHTS     (AG_FONT_BOLD | AG_FONT_SW_BOLD)
#define AG_FONT_STYLES      (AG_FONT_ITALIC | AG_FONT_SW_ITALIC | \\
                             AG_FONT_OBLIQUE | AG_FONT_UPRIGHT_ITALIC) 
#define AG_FONT_WD_VARIANTS (AG_FONT_SEMICONDENSED | AG_FONT_CONDENSED)

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 the face or size arguments are NULL then AG_FetchFont() uses the AG_Config(3) defaults `font.face' and `font.size'. AG_FetchFont() returns a pointer to the font object and increments its reference count. If the font cannot be loaded, it 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. A pointer to the previous default font is returned.

AG_TextParseFontSpec() parses a "<Face>[:<Size>][:<Style>]" format specification, loads the matching font and (if successful) sets it as the default font. Exceptionally, it is safe to invoke AG_TextParseFontSpec() before the initial AG_InitGraphics() call so that the default font can be set from a command-line argument. If fontspec is NULL then it's a no-op.

Field separators "," and "/" are also recognized in addition to ":". Possible Style flags include "b" = bold, "i" = italic, "I" = upright italic and "U" = uppercase.

HISTORY

The AG_Text interface first appeared in Agar 1.0. Rendering attributes were introduced in Agar 1.3. Fontconfig support was added in Agar 1.5. Upright Italic and width variants were added in Agar 1.6.0. AG_CopyTextState() and AG_TextFontPctFlags() appeared in Agar 1.6.0.