.\" Copyright (c) 2002-2008 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 April 24, 2003
.Dt AG_TEXT 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Text
.Nd agar text rendering interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
interface uses an underlying font engine to render text.
Currently, two font engines are supported:
.Dv AG_FONT_VECTOR
(for rendering any font supported by FreeType) and
.Dv AG_FONT_BITMAP
(for rendering simple pixmap fonts).
.Sh RENDER SETTINGS
A number of settings which affect the rendering functions (see
.Dq RENDERING
section) can be modified at any time, and are organized in a stack of
rendering attributes.
.Pp
.nr nS 1
.Ft void
.Fn AG_PushTextState "void"
.Pp
.Ft void
.Fn AG_PopTextState "void"
.Pp
.Ft int
.Fn AG_TextFont "const char *face" "int size" "Uint flags"
.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_TextColorVideo32 "Uint32 pixel"
.Pp
.Ft void
.Fn AG_TextColor32 "Uint32 pixel"
.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_TextBGColorVideo32 "Uint32 pixel"
.Pp
.Ft void
.Fn AG_TextBGColor32 "Uint32 pixel"
.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
.nr nS 0
The
.Fn AG_PushTextState
and
.Fn AG_PopTextState
functions respectively push and pop the text rendering attribute stack.
The attribute stack can hold
.Dv AG_TEXT_STATES_MAX
items (at least 32).
.Pp
.Fn AG_TextFont
searches the font cache for the given font face, size and flags combination,
possibly loading new fonts from disk (scanning all
.Sq font-path
directories).
It returns 0 on success or -1 if no suitable combination was found.
.Pp
.Fn AG_TextJustify
selects the justification mode to use in multi-line rendering:
.Bd -literal
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 where text is rendered to an
area of arbitrary height:
.Bd -literal
enum ag_text_valign {
	AG_TEXT_TOP,
	AG_TEXT_MIDDLE,
	AG_TEXT_BOTTOM
};
.Ed
.Pp
.Fn AG_TextColorVideo32
sets the text color using the given pixel in
.Va agVideoFmt
format.
.Fn AG_TextColor32
accepts a pixel in
.Va agSurfaceFmt
format.
.Fn AG_TextColorRGB
and
.Fn AG_TextColorRGBA
accept individual color components.
.Pp
Similarly,
.Fn AG_TextBG*
functions assign a background color for the surfaces returned by the
rendering functions.
.Sh RENDERING
.nr nS 1
.Ft "AG_Surface *"
.Fn AG_TextRender "const char *text"
.Pp
.Ft "AG_Surface *"
.Fn AG_TextRenderUCS4 "const Uint32 *text"
.Pp
.Ft "AG_Surface *"
.Fn AG_TextRenderf "const char *fmt" "..."
.Pp
.Ft "AG_Glyph *"
.Fn AG_TextRenderGlyph "Uint32 uch"
.Pp
.Ft void
.Fn AG_TextUnusedGlyph "AG_Glyph *glyph"
.Pp
.Ft "void"
.Fn AG_TextSize "const char *text" "int *w" "int *h"
.Pp
.Ft "void"
.Fn AG_TextSizeUCS4 "const Uint32 *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_TextSizeMultiUCS4 "const Uint32 *text" "int *w" "int *h" "Uint **wLines" "Uint *nLines"
.Pp
.nr nS 0
The
.Fn AG_TextRender
function renders text to a new, transparent surface.
The input text may contain UTF-8 sequences.
The
.Fn AG_TextRenderf
variant accepts
.Xr printf 3
style arguments.
.Pp
.Fn AG_TextRenderUCS4
renders text in UCS-4 format onto a new surface.
.Fn AG_TextRenderGlyph
renders the specified UCS-4 encoded Unicode character.
The function returns an
.Ft AG_Glyph
structure, which has the following public (read-only) members:
.Pp
.Bl -tag -compact -width "float texcoord[4] "
.It Uint32 ch
Unicode character (UCS-4 encoded)
.It AG_Surface *su
Pixel 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
Amount of translation (in pixels) recommended to follow when rendering text
.El
.Pp
.Fn AG_TextUnusedGlyph
must be invoked when an
.Ft AG_Glyph
object is no longer needed.
.Pp
The
.Fn AG_TextSize
and
.Fn AG_TextSizeUCS4
functions return the minimal bounding box in pixels required for rendering the
given text.
The
.Fn AG_TextSizeMulti
and
.Fn AG_TextSizeMultiUCS4
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 CANNED DIALOGS
.nr nS 1
.Ft "void"
.Fn AG_TextMsg "enum ag_text_msg_title title" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextMsgFromError "void"
.Pp
.Ft "void"
.Fn AG_TextWarning "const char *disableKey" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextError "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextInfo "const char *disableKey" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextTmsg "enum ag_text_msg_title title" "Uint32 expire" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextEditFloat "double *fp" "double min" "double max" "const AG_Unit *unit" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_TextEditString "char *buf" "size_t len" "const char *format" "..."
.Pp
.Ft "void"
.Fn "AG_TextPromptString" "const char *prompt" "void (*ok_fn)(AG_Event *)" "const char *fmt" "..."
.Pp
.Ft "AG_Window *"
.Fn AG_TextPromptOptions "AG_Button **buttons" "Uint nButtons" "const char *format" "..."
.Pp
.nr nS 0
The
.Fn AG_TextMsg
function displays a text message window containing the given
.Xr printf 3
formatted string, and an
.Sq OK
button.
.Fa title
is one of the following:
.Pp
.Bd -literal
enum ag_text_msg_title {
	AG_MSG_ERROR,
	AG_MSG_WARNING,
	AG_MSG_INFO
};
.Ed
.Pp
.Fn AG_TextMsgFromError
displays a standard error message using the value of
.Xr AG_GetError 3 .
.Pp
.Fn AG_TextWarning
displays a standard warning message, but also provides the user
with a
.Dq Don't show again
checkbox.
The checkbox controls the
.Xr AG_Config 3
value specified by
.Fa disableKey .
.Pp
.Fn AG_TextError
displays an error message.
It is equivalent to
.Fn AG_TextMsg
with a
.Dv AG_MSG_ERROR
setting.
.Pp
.Fn AG_TextInfo
displays an informational message.
Similar to
.Fn AG_TextWarning ,
a
.Dq Don't show again
option is provided to the user (and the setting is referenced by
.Fa disableKey ) .
.Pp
The
.Fn AG_TextTmsg
routine is a variant of
.Fn AG_TextMsg
which displays the message for a specific amount of time, given in milliseconds.
.Pp
The
.Fn AG_TextEditFloat
function displays a dialog asking for a floating-point value.
The
.Fa fp
argument is a pointer to the variable, while
.Fa min
and
.Fa max
define the acceptable range.
Unless
.Fa unit
is NULL, the argument indicates the unit system to use (as in
.Xr AG_Units 3 ) .
.Pp
Similarly,
.Fn AG_TextEditString
displays a dialog asking for a string, where
.Fa buf
is a pointer to the string buffer, and
.Fa len
is the size of the buffer.
.Pp
The
.Fn AG_TextPromptString
creates a modal dialog asking the user for a text string.
Once the user confirms the entry, the
.Fn ok_fn
callback is invoked (see
.Xr AG_Event 3
for details on the argument format).
The entered string is the last argument on the stack.
.Pp
.Fn AG_TextPromptOptions
creates a dialog displaying a text string and an array of buttons.
.Fa buttons
is a set of existing
.Xr AG_Button 3
widgets to display.
.Sh FONT SELECTION
.nr nS 1
.Ft "AG_Font *"
.Fn AG_FetchFont "const char *face" "int points" "int flags"
.Pp
.Ft void
.Fn AG_DestroyFont "AG_Font *font"
.Pp
.Ft void
.Fn AG_SetDefaultFont "AG_Font *font"
.Pp
.Ft void
.Fn AG_TextParseFontSpec "const char *fontspec"
.Pp
.nr nS 0
The
.Fn AG_TextParseFontSpec
function parses a font specification of the form
.Sq face,size,style
(valid separators include
.Sq :,./ )
and assigns the default font.
This function is typically called prior to
.Fn AG_InitVideo
(ie. to parse alternate fonts specified on the command line).
The default font is selected from the following
.Xr AG_Config 3
settings:
.Bl -tag -width "font.flags "
.It Va font.face
This specifies the filename of the default font to use.
The file should reside in one of the directories specified in the
.Va font-path
.Xr AG_Config 3
setting.
.It Va font.size
The default font size in points.
.It Va font.flags
The default font attribute flags.
The meaning of this parameter is specific to the underlying font engine.
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Config 3 ,
.Xr AG_Button 3 ,
.Xr AG_Combo 3 ,
.Xr AG_Label 3 ,
.Xr AG_Radio 3 ,
.Xr AG_Statusbar 3 ,
.Xr AG_Surface 3 ,
.Xr AG_Numerical 3 ,
.Xr AG_Textbox 3 ,
.Xr AG_Titlebar 3 ,
.Xr AG_Tlist 3 ,
.Xr AG_UCombo 3 ,
.Xr AG_Widget 3
.Bd -literal
The FreeType project - http://www.freetype.org/
Unicode home page - http://www.unicode.org/
.Ed
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.0.
The stack of rendering attributes was added in Agar 1.3.