Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_TEXT(3)	       FreeBSD Library Functions Manual		    AG_TEXT(3)

NAME
     AG_Text --	agar text rendering interface

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

DESCRIPTION
     The AG_Text interface uses	an underlying font engine to render text.
     Currently,	two font engines are supported:	AG_FONT_VECTOR (for rendering
     any font supported	by FreeType) and AG_FONT_BITMAP	(for rendering simple
     pixmap fonts).

RENDER SETTINGS
     A number of settings which	affect the rendering functions (see RENDERING
     section) can be modified at any time, and are organized in	a stack	of
     rendering attributes.

     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 percent-
     age of current font size.	An argument of 100% leaves the size unchanged.

     AG_TextJustify() selects the justification	mode to	use in multi-line ren-
     dering:

     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 sur-
     faces returned by the rendering functions.

RENDERING
     AG_Surface	* AG_TextRender(const char *text)

     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 charac-
     ter.  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 fol-
			 low 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_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)

     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 indi-
     cates 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
     AG_Font * AG_FetchFont(const char *face, int size,	int flags)

     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 spec-
     ified 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	com-
     mand line).

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)

     The FreeType project: http://www.freetype.org/

     Unicode home page:	http://www.unicode.org/

HISTORY
     The AG_Text interface first appeared in Agar 1.0.	The stack of rendering
     attributes	was added in Agar 1.3.	Right-to-left rendering	first appeared
     in	Agar 1.4.1.

FreeBSD	13.0			April 24, 2003			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RENDER SETTINGS | RENDERING | CANNED DIALOGS | FONT SELECTION | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Text&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help