SYNOPSIS
|
DESCRIPTION
![]() |
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. 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:
AG_TextValign() selects the vertical alignment mode to use where text is rendered to an area of arbitrary height:
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
CANNED DIALOGS
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. |
FONT SELECTION
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:
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. |
SEE ALSO
AG_Config(3), AG_Editable(3), AG_Intro(3), AG_Label(3), AG_Surface(3), AG_Textbox(3), AG_TextElement(3), AG_Widget(3) Lk http://www.freetype.org/ FreeType Lk http://www.unicode.org/ Unicode Lk https://www.freedesktop.org/wiki/Software/fontconfig/ Fontconfig |
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. |