NAME

AG_Text — agar text rendering interface

SYNOPSIS

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

DESCRIPTION

The AG_Text interface allows Agar GUI widgets to render and display text. Different font engines are supported. AG_FontFt(3) handles vector fonts through FreeType and AG_FontBf(3) handles Agar bitmap font (.agbf) files.

RENDERING

AG_Surface *
AG_TextRender(const char *text);

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

AG_Surface *
AG_TextRenderRTL(const char *text);

AG_Surface *
AG_TextRenderCropped(const char *text);

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 (see RENDERING ATTRIBUTES section). The input text may contain UTF-8 characters and ANSI SGR sequences. The first guide (Guide 0) of the surface returned by AG_TextRender() contains ascent information.

The AG_TextRenderRTL() variant of AG_TextRender() renders text reversed (right to left).

The AG_TextRenderCropped() variant of AG_TextRender() crops the returned surface to the precise boundaries of the rendered text contents. This fast crop operation leaves the cropped (all-transparent) pixels in memory. AG_TextRenderCropped() can be used for condensing or removing typographical spacings so that individual glyphs (for example "Geometrical Shapes") can be aligned precisely inside widget controls.

AG_TextRenderInternal() renders onto a newly-allocated surface text in native AG_Char encoding (which is normally UCS-4, but can be char in non AG_UNICODE builds).

The AG_TextRenderGlyph() function returns a pointer to the corresponding AG_Glyph from the cache (rendering it on demand if needed). The AG_Glyph structure includes the following (read-only) fields:

AG_Char ch: Native character (normally UCS-4).
AG_Surface *su: Rendered graphical surface.
Uint texture: OpenGL texture handle (if OpenGL is in use).
float texcoord[4]: OpenGL texture coordinates (if OpenGL is in use).
int advance: Recommended horizontal translation (in pixels).

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).

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: These functions are *not* free-threaded and are only safe to invoke from the draw(), size_request(), size_allocate() or from 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_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() searches the cache for a combination of font face, size and style flags, possibly loading the font from disk. On success, the font becomes the active font of the text state and a pointer to it is returned. On failure, AG_TextFontLookup() returns NULL.

AG_TextFontPts() sets the size of the active font in points. If the argument nears 0.0 (up to AG_FONT_PTS_EPSILON) then the AG_Config(3) default 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 justification mode for 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 if the text is to be rendered to a height different than the font's bounding box:

enum ag_text_valign {
	AG_TEXT_TOP,
	AG_TEXT_MIDDLE,
	AG_TEXT_BOTTOM
};

AG_TextTabWidth() sets the width of tabs (`\t' characters) in pixels.

AG_TextColor() sets the text color (see AG_Color(3)). Component-wise variants AG_TextColorRGB() and AG_TextColorRGBA() are also available.

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). The ANSI color palette is copy-on-write (i.e., palette data gets copied to the active AG_TextState structure on demand only if a modification occurs).

FONTS

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

AG_Font *
AG_FetchFontFromList(const char *faceList, float size, Uint flags);

AG_Font *
AG_SetDefaultFont(AG_Font *font);

void
AG_TextParseFontSpec(const char *fontspec);

int
AG_FontGetFamilyStyles(AG_Font *font);

AG_Size
AG_FontGetStyleName(char *buf, AG_Size bufSize, Uint flags);

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

#define AG_FONT_THIN           0x0001 /* Wt#100 */
#define AG_FONT_EXTRALIGHT     0x0002 /* Wt#200 */
#define AG_FONT_LIGHT          0x0004 /* Wt#300 */
                                      /* Wt#400 */
#define AG_FONT_SEMIBOLD       0x0008 /* Wt#600 */
#define AG_FONT_BOLD           0x0010 /* Wt#700 */
#define AG_FONT_EXTRABOLD      0x0020 /* Wt#800 */
#define AG_FONT_BLACK          0x0040 /* Wt#900 */

#define AG_FONT_OBLIQUE        0x0080 /* Oblique */
#define AG_FONT_ITALIC         0x0100 /* Italic */

#define AG_FONT_ULTRACONDENSED 0x0400 /* Wd 50% */
#define AG_FONT_CONDENSED      0x0800 /* Wd 75% */
#define AG_FONT_SEMICONDENSED  0x1000 /* Wd 87.5% */
#define AG_FONT_SEMIEXPANDED   0x2000 /* Wd 112.5% */
#define AG_FONT_EXPANDED       0x4000 /* Wd 125% */
#define AG_FONT_ULTRAEXPANDED  0x8000 /* Wd 200% */

The following bitmasks can be useful to isolate or sort by weight, style and width variant:

#define AG_FONT_WEIGHTS (AG_FONT_THIN | AG_FONT_EXTRALIGHT | \
                         AG_FONT_LIGHT | AG_FONT_SEMIBOLD | \
                         AG_FONT_BOLD | AG_FONT_EXTRABOLD | \
                         AG_FONT_BLACK)

#define AG_FONT_STYLES (AG_FONT_OBLIQUE | AG_FONT_ITALIC)

#define AG_FONT_WD_VARIANTS (AG_FONT_ULTRACONDENSED | \
                             AG_FONT_CONDENSED | \
                             AG_FONT_SEMICONDENSED | \
                             AG_FONT_SEMIEXPANDED | \
                             AG_FONT_EXPANDED | \
                             AG_FONT_ULTRAEXPANDED)

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. AG_FetchFont() returns a pointer to the loaded font object in cache. If the font cannot be loaded, it returns NULL.

The AG_FetchFontFromList() function is a variant of AG_FetchFont() which accepts a comma-separated list of font faces and returns the first font from the list which can be found and loaded successfully.

AG_SetDefaultFont() sets the specified font object as the default font. A pointer to the previous default font is returned.

The AG_TextParseFontSpec() routine parses a command-line friendly string of the form "<Face>[:<Size>][:<Style>]". It 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 before initialization. If fontspec is NULL then it's a no-op. Field separators "," and "/" are also recognized in addition to ":".

The Size field is given in points (fractional point sizes are allowed). The Style field may include (any combination of) style / weight / width variants separated by spaces. Weight attributes are: "Thin", "ExtraLight", "Light", "Regular", "SemiBold", "Bold", "ExtraBold" and "Black". Style attributes are: "Oblique", "Italic" and "Regular". Width variants are: "UltraCondensed", "Condensed", "SemiCondensed", "Regular", "SemiExpanded", "Expanded" and "UltraExpanded".

The AG_FontGetFamilyStyles() function searches for every style (style, weight and width variant combination) available under the family of font and produces a compact array of AG_Font flags. On success, it updates the familyFlags array and the nFamilyFlags counter of font. On failure, it sets the error message and returns -1.

AG_FontGetStyleName() generates a string for the given set of AG_Font flags. The string is written to a fixed-size buffer buf and the function returns the number of bytes that would have been copied were bufSize unlimited. The resulting representation should be compatible with the FC_STYLE names used by Fontconfig.

ANSI ATTRIBUTES

int
AG_TextParseANSI(const AG_TextState *state, AG_TextANSI *ansi, const AG_Char *s);

int
AG_TextExportUnicode_StripANSI(const char *encoding, char *dst, const AG_Char *src, AG_Size dstSize);

AG_TextParseANSI() interprets a possible ANSI sequence attribute in a native (UCS-4) string s and returns 0 if a valid sequence is found, otherwise it returns -1. If a valid sequence is found, AG_TextParseANSI() writes a normalized description of it into the ansi structure and the total length of the sequence in its len field. Stripping ANSI sequences from a string while it is being exported can be done simply by skipping over len characters whenever a valid sequence is found.

AG_TextExportUnicode_StripANSI() converts the contents of the given UCS-4 text buffer to the specified encoding and strips ANSI attribute sequences in the process. "US-ASCII and "UTF-8" encodings are handled internally by Agar. Other encodings are handled through iconv where available. The resulting text is written to the specified buffer dst, which should be of the specified size dstSize, in bytes. The written string is always NUL-terminated.

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.

HISTORY

The AG_Text interface first appeared in Agar 1.0. Rendering attributes were introduced in 1.3.x. Fontconfig support was added in 1.5.x. AG_CopyTextState() and AG_TextFontPctFlags() appeared in 1.6.0. Support for all standard weights and width variants appeared in 1.7.0. Ascent guides in AG_TextRender() generated surfaces appeared in 1.7.0.