NAME

SYNOPSIS

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

DESCRIPTION

RENDER SETTINGS

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_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_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, ...);

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

void
AG_UnusedFont(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 font corresponding to the specified face and size in points. Acceptable 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 any the parameters are specified as NULL or -1, the AG_Config(3) defaults font.face, font.size and font.flags 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).

SEE ALSO

The FreeType project

Unicode home page

HISTORY