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.

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

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.


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

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:
The following bitmasks can be useful to isolate or sort by weight, style and width variant:
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.

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.

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

AG_Config(3), AG_Editable(3), AG_Intro(3), AG_Label(3), AG_Surface(3), AG_Textbox(3), AG_TextElement(3), AG_Widget(3)

•  FreeType
  
•  Fontconfig
  
•  Unicode

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.