.\" Copyright (c) 2002-2023 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_TEXT 3 .Os Agar 1.7 .Sh NAME .Nm AG_Text .Nd agar text rendering interface .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" IMAGE(/widgets/AG_Textbox.png, "The AG_Textbox(3) widget") The .Nm interface allows Agar GUI widgets to render and display text. Different font engines are supported. .Xr AG_FontFt 3 handles vector fonts through FreeType and .Xr AG_FontBf 3 handles Agar bitmap font (.agbf) files. .Sh RENDERING .nr nS 1 .Ft "AG_Surface *" .Fn AG_TextRender "const char *text" .Pp .Ft "AG_Surface *" .Fn AG_TextRenderF "const char *fmt" "..." .Pp .Ft "AG_Surface *" .Fn AG_TextRenderRTL "const char *text" .Pp .Ft "AG_Surface *" .Fn AG_TextRenderCropped "const char *text" .Pp .Ft "AG_Surface *" .Fn AG_TextRenderInternal "const AG_Char *text" "const AG_Font *font" "const AG_Color *cBg" "const AG_Color *cFg" .Pp .Ft "AG_Glyph *" .Fn AG_TextRenderGlyph "AG_Driver *drv" "const AG_Font *font" "const AG_Color *cBg" "const AG_Color *cFg" "AG_Char ch" .Pp .Ft "void" .Fn AG_TextSize "const char *text" "int *w" "int *h" .Pp .Ft "void" .Fn AG_TextSizeInternal "const AG_Char *text" "int *w" "int *h" .Pp .Ft "void" .Fn AG_TextSizeMulti "const char *text" "int *w" "int *h" "Uint **wLines" "Uint *nLines" .Pp .Ft "void" .Fn AG_TextSizeMultiInternal "const AG_Char *text" "int *w" "int *h" "Uint **wLines" "Uint *nLines" .Pp .nr nS 0 .Fn AG_TextRender renders the C string .Fa text onto a newly-allocated surface. The font, colors and spacings are according to the current rendering attributes (see .Sx RENDERING ATTRIBUTES section). The input .Fa text may contain UTF-8 characters and ANSI SGR sequences. The first guide (Guide 0) of the surface returned by .Fn AG_TextRender contains .Em ascent information. .Pp The .Fn AG_TextRenderRTL variant of .Fn AG_TextRender renders text reversed (right to left). .Pp The .Fn AG_TextRenderCropped variant of .Fn 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. .Fn 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. .Pp .Fn AG_TextRenderInternal renders onto a newly-allocated surface text in native .Ft AG_Char encoding (which is normally UCS-4, but can be .Ft char in non .Dv AG_UNICODE builds). .Pp The .Fn AG_TextRenderGlyph function returns a pointer to the corresponding .Ft AG_Glyph from the cache (rendering it on demand if needed). The .Ft AG_Glyph structure includes the following (read-only) fields: .Pp .Bl -tag -compact -width "float texcoord[4] " .It AG_Char ch Native character (normally UCS-4). .It AG_Surface *su Rendered graphical surface. .It Uint texture OpenGL texture handle (if OpenGL is in use). .It float texcoord[4] OpenGL texture coordinates (if OpenGL is in use). .It int advance Recommended horizontal translation (in pixels). .El .Pp The .Fn AG_TextSize and .Fn AG_TextSizeInternal functions return the minimal bounding box in pixels required for rendering the given text. The .Fn AG_TextSizeMulti and .Fn AG_TextSizeMultiInternal variants also return the number of lines into .Fa nLines and the width in pixels of each line in the array .Fa wLines (which must be initialized to NULL). .Sh 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 .Fn AG_TextFont or .Fn AG_TextColor . .Pp Note: These functions are *not* free-threaded and are only safe to invoke from the .Fn draw , .Fn size_request , .Fn size_allocate or from any event handler of an .Xr AG_Widget 3 with the .Dv AG_WIDGET_USE_TEXT flag set. .Pp .nr nS 1 .Ft void .Fn AG_PushTextState "void" .Pp .Ft void .Fn AG_CopyTextState "AG_TextState *dst" .Pp .Ft void .Fn AG_PopTextState "void" .Pp .Ft "AG_TextState *" .Fn AG_TEXT_STATE_CUR "void" .Pp .Ft void .Fn AG_TextFont "AG_Font *font" .Pp .Ft "AG_Font *" .Fn AG_TextFontLookup "const char *face" "float points" "Uint flags" .Pp .Ft "AG_Font *" .Fn AG_TextFontPct "int size_pct" .Pp .Ft "AG_Font *" .Fn AG_TextFontPctFlags "int size_pct" "Uint flags" .Pp .Ft "AG_Font *" .Fn AG_TextFontPts "float size" .Pp .Ft void .Fn AG_TextJustify "enum ag_text_justify mode" .Pp .Ft void .Fn AG_TextValign "enum ag_text_valign mode" .Pp .Ft void .Fn AG_TextTabWidth "int pixels" .Pp .Ft void .Fn AG_TextColor "const AG_Color *c" .Pp .Ft void .Fn AG_TextColorRGB "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft void .Fn AG_TextColorRGBA "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft void .Fn AG_TextBGColor "const AG_Color *c" .Pp .Ft void .Fn AG_TextBGColorRGB "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft void .Fn AG_TextBGColorRGBA "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft void .Fn AG_TextBGColorRGBA "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft void .Fn AG_TextColorANSI "enum ag_ansi_color which" "const AG_Color *c" .Pp .nr nS 0 .Fn AG_PushTextState increments the attribute stack pointer and creates a copy of the previous state in the current state. .Fn AG_PopTextState decrements the stack pointer, discarding the current state. .Fn AG_CopyTextState copies the current text state to .Fa dst . The text state stack can hold up to .Dv AG_TEXT_STATES_MAX elements. .Pp The .Fn AG_TEXT_STATE_CUR macro expands to an expression returning the pointer to the current .Ft AG_TextState . In debug mode, an additional validity test is performed. .Pp The .Fn AG_TextFont function selects .Fa font as the active font. .Pp .Fn 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, .Fn AG_TextFontLookup returns NULL. .Pp .Fn AG_TextFontPts sets the size of the active font in points. If the argument nears 0.0 (up to .Dv AG_FONT_PTS_EPSILON ) then the .Xr AG_Config 3 default is used. .Pp .Fn AG_TextFontPct sets the size of the active font, specified as percentage of current font size. An argument of 100% leaves the size unchanged. .Fn AG_TextFontPctFlags allows an alternate font style via .Fa flags argument. .Pp .Fn AG_TextJustify selects the justification mode for multi-line rendering: .Bd -literal .\" SYNTAX(c) enum ag_text_justify { AG_TEXT_LEFT, AG_TEXT_CENTER, AG_TEXT_RIGHT }; .Ed .Pp .Fn 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: .Bd -literal .\" SYNTAX(c) enum ag_text_valign { AG_TEXT_TOP, AG_TEXT_MIDDLE, AG_TEXT_BOTTOM }; .Ed .Pp .Fn AG_TextTabWidth sets the width of tabs (`\\t' characters) in pixels. .Pp .Fn AG_TextColor sets the text color (see .Xr AG_Color 3 ) . Component-wise variants .Fn AG_TextColorRGB and .Fn AG_TextColorRGBA are also available. .Pp Similarly, .Fn AG_TextBG* functions assign a background color for the surfaces returned by the rendering functions. .Pp .Fn AG_TextColorANSI modifies an entry in the 4-bit ANSI color palette. Subsequent calls to .Fn AG_TextRender will display text containing .Dv AG_SGR_FG* or .Dv AG_SGR_BG* sequences in the specified color (until .Fn AG_PopTextState is called). The ANSI color palette is copy-on-write (i.e., palette data gets copied to the active .Ft AG_TextState structure on demand only if a modification occurs). .Sh FONTS .nr nS 1 .Ft "AG_Font *" .Fn AG_FetchFont "const char *face" "float size" "Uint flags" .Pp .Ft "AG_Font *" .Fn AG_FetchFontFromList "const char *faceList" "float size" "Uint flags" .Pp .Ft "AG_Font *" .Fn AG_SetDefaultFont "AG_Font *font" .Pp .Ft void .Fn AG_TextParseFontSpec "const char *fontspec" .Pp .Ft int .Fn AG_FontGetFamilyStyles "AG_Font *font" .Pp .Ft AG_Size .Fn AG_FontGetStyleName "char *buf" "AG_Size bufSize" "Uint flags" .Pp .nr nS 0 The .Fn AG_FetchFont function loads (or retrieves from cache) the font corresponding to the specified .Fa face , .Fa size and style .Fa flags . Face may refer to either a system-wide font or a file in .Va font-path . .Fa size is in points (fractional sizes are permitted). Style .Fa flags are as follows: .Bd -literal -offset indent .\" SYNTAX(c) #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% */ .Ed .Pp The following bitmasks can be useful to isolate or sort by weight, style and width variant: .Bd -literal -offset indent .\" SYNTAX(c) #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) .Ed .Pp 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 .Va font-path setting). .Pp If the .Fa face or .Fa size arguments are NULL then .Fn AG_FetchFont uses the .Xr AG_Config 3 defaults. .Fn AG_FetchFont returns a pointer to the loaded font object in cache. If the font cannot be loaded, it returns NULL. .Pp The .Fn AG_FetchFontFromList function is a variant of .Fn 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. .Pp .Fn AG_SetDefaultFont sets the specified font object as the default font. A pointer to the previous default font is returned. .Pp The .Fn AG_TextParseFontSpec routine parses a command-line friendly string of the form "[:][: