.\" Copyright (c) 2002-2007 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 August 21, 2002
.Dt AG_TEXTBOX 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Textbox
.Nd agar text box widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget allows the user to edit UTF-8 encoded text.
It provides the basic
.Xr AG_Editable 3
interface and adds a built-in text label, cosmetics and scrollbars in
multiline mode.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Textbox *"
.Fn AG_TextboxNew "AG_Widget *parent" "Uint flags" "const char *label"
.Pp
.Ft "void"
.Fn AG_TextboxBindUTF8 "AG_Textbox *textbox" "char *buffer" "size_t bufferSize"
.Pp
.Ft "void"
.Fn AG_TextboxBindASCII "AG_Textbox *textbox" "char *buffer" "size_t bufferSize"
.Pp
.Ft void
.Fn AG_TextboxSetStatic "AG_Textbox *textbox" "int enable"
.Pp
.Ft void
.Fn AG_TextboxSetPassword "AG_Textbox *textbox" "int password"
.Pp
.Ft void
.Fn AG_TextboxSetIntOnly "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_TextboxSetFltOnly "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_TextboxSetLabel "AG_Textbox *textbox" "const char *fmt" "..."
.Pp
.Ft void
.Fn AG_TextboxSizeHint "AG_Textbox *textbox" "const char *text"
.Pp
.Ft void
.Fn AG_TextboxSizeHintPixels "AG_Textbox *textbox" "Uint w" "Uint h"
.Pp
.Ft void
.Fn AG_TextboxSizeHintLines "AG_Textbox *textbox" "Uint nLines"
.Pp
.nr nS 0
The
.Fn AG_TextboxNew
function allocates, initializes, and attaches a new
.Nm
widget.
The
.Fa label
parameter (if not NULL) defines an optional text label to display left
of the textbox.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_TEXTBOX_ABANDON_FOCUS "
.It AG_TEXTBOX_MULTILINE
Causes newlines to be entered literally into the string, and arranges for
horizontal and vertical scrollbars to appear if the text is larger than the
display area.
.It AG_TEXTBOX_STATIC
Enable some important optimizations based on the assumption that the contents
of the buffer will not change under the widget's feet.
The default behavior makes no such assumption, possibly resulting in frequent
character set conversions.
.It AG_TEXTBOX_PASSWORD
Password-style entry where characters are hidden.
.Fn AG_TextboxSetPassword
sets this flag.
.It AG_TEXTBOX_ABANDON_FOCUS
Arrange for the widget to abandon its focus when the return key is pressed.
.It AG_TEXTBOX_INT_ONLY
Restricts input to valid integers only.
Use
.Fn AG_TextboxSetIntOnly
to change at runtime.
.It AG_TEXTBOX_FLT_ONLY
Restricts input to valid floating-point numbers in decimal and scientific
notation ("inf" and the Unicode symbol for Infinity may also be used).
Use
.Fn AG_TextboxSetFltOnly
to change at runtime.
.It AG_TEXTBOX_CATCH_TAB
Cause tabs to be entered literally into the string (by default, the tab
key moves focus to the next widget).
.It AG_TEXTBOX_NOEMACS
Disable emacs-style function keys.
.It AG_TEXTBOX_NOWORDSEEK
Disable the emacs-style ALT-f and ALT-b keys which conflict with traditional
LATIN-1 combinations.
.It AG_TEXTBOX_NOLATIN1
Disable traditional LATIN-1 key combinations.
.El
.Pp
The
.Fn AG_TextboxBindUTF8
and
.Fn AG_TextboxBindASCII
functions bind the textbox to a text buffer in UTF-8 or plain ASCII encoding,
respectively.
The
.Fa bufferSize
argument indicates the complete size of the buffer in bytes.
.Pp
The
.Fn AG_TextboxSetStatic
function enables or disables static optimizations at runtime (see
.Dv AG_TEXTBOX_STATIC
flag description).
.Pp
.Pp
The
.Fn AG_TextboxSetPassword
function enables/disables password-type input, where characters are substituted
for
.Sq *
in the display.
.Pp
.Fn AG_TextboxSetIntOnly
restricts input to integers (see flags)
.Fn AG_TextboxSetFltOnly
restricts input to real numbers (see flags).
.Pp
.Pp
.Fn AG_TextboxSetLabel
changes the current label text to the specified string.
.Pp
.Fn AG_TextboxSizeHint
requests that the initial geometry of
.Fa textbox
is to be sufficient to display the string
.Fa text
in its entirety.
The
.Fn AG_TextboxSizeHintPixels
variant accepts arguments in pixels.
.Fn AG_TextboxSizeHintLines
accepts a number of lines.
.Sh CURSOR MANIPULATION
.nr nS 1
.Ft int
.Fn AG_TextboxMapPosition "AG_Textbox *textbox" "int x" "int y" "int *pos" "int absolute"
.Pp
.Ft void
.Fn AG_TextboxMoveCursor "AG_Textbox *textbox" "int x" "int y" "int absolute"
.Pp
.Ft int
.Fn AG_TextboxGetCursorPos "AG_Textbox *textbox"
.Pp
.Ft int
.Fn AG_TextboxSetCursorPos "AG_Textbox *textbox" "int pos"
.Pp
.nr nS 0
The
.Fn AG_TextboxMapPosition
function translates absolute coordinates (such as display coordinates)
.Fa x
and
.Fa y
in pixels to a position in the text buffer and return this position into
.Fa pos .
The function returns -1 or 1 if the cursor lies before or after the end
of the string, respectively.
If
.Fa absolute
if 1, y coordinates outside of the widget area are allowed.
.Pp
.Fn AG_TextboxGetCursorPos
returns the current position of the cursor in the buffer.
Under multithreading, the return value is only valid as long as the widget is
locked.
.Pp
.Fn AG_TextboxSetCursorPos
tries to move the cursor to the specified position in the string, after
bounds checking is done.
If
.Fa pos
is -1, the cursor is moved to the end of the string.
.Fn AG_TextboxSetCursorPos
returns the new position of the cursor.
.Sh TEXT MANIPULATION
.nr nS 1
.Ft void
.Fn AG_TextboxPrintf "AG_Textbox *textbox" "const char *fmt" "..."
.Pp
.Ft void
.Fn AG_TextboxSetString "AG_Textbox *textbox" "const char *s"
.Pp
.Ft void
.Fn AG_TextboxSetStringUCS4 "AG_Textbox *textbox" "const Uint32 *s"
.Pp
.Ft void
.Fn AG_TextboxClearString "AG_Textbox *textbox"
.Pp
.Ft "char *"
.Fn AG_TextboxDupString "AG_Textbox *textbox"
.Pp
.Ft "size_t"
.Fn AG_TextboxCopyString "AG_Textbox *textbox" "char *dst" "size_t dst_size"
.Pp
.Ft "void"
.Fn AG_TextboxBufferChanged "AG_Textbox *textbox"
.Pp
.Ft int
.Fn AG_TextboxInt "AG_Textbox *textbox"
.Pp
.Ft float
.Fn AG_TextboxFlt "AG_Textbox *textbox"
.Pp
.Ft double
.Fn AG_TextboxDbl "AG_Textbox *textbox"
.Pp
.nr nS 0
The
.Fn AG_TextboxPrintf
function uses
.Xr vsnprintf 3
to overwrite the contents of the buffer.
If the
.Fa fmt
argument is NULL, a NUL string is assigned instead.
.Pp
.Fn AG_TextboxSetString
overwrites the contents of the buffer with the given string.
The argument may be NULL to clear the string.
.Fn AG_TextboxSetStringUCS4
accepts a string in UCS-4 encoding.
.Pp
.Fn AG_TextboxClearString
clears the contents of the buffer.
.Pp
The
.Fn AG_TextboxDupString
function returns a copy of the text buffer.
.Pp
The
.Fn AG_TextboxCopyString
function copies up to
.Fa dst_size
- 1 bytes from the text buffer
.Fa dst ,
NUL-terminating the result and returning the number of bytes that would
have been copied if
.Fa dst_size
was unlimited.
.Pp
The
.Fn AG_TextboxBufferChanged
function signals an outside change in the buffer contents.
It is only useful if the
.Nm AG_TEXTBOX_STATIC
flag is set.
.Pp
.Fn AG_TextboxInt ,
.Fn AG_TextboxFlt
and
.Fn AG_TextboxDbl
perform conversion of the string contents to
.Ft int
.Ft float
and
.Ft double ,
respectively and return the value.
You probably want to be using the
.Xr AG_Numerical 3
widget instead of these functions.
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "char *string "
.It Va char *string
Text buffer using UTF-8 encoding.
.El
.Sh EVENTS
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width 25n
.It window-mousebuttondown
Move focus to the widget.
Position the cursor at a specific position.
.It window-mousemotion
Move the cursor and scroll.
.It window-keydown
Perform the action that the current keymap associates with this key.
.El
.Pp
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -width 2n
.It Fn textbox-return "void"
Return was pressed and
.Dv AG_TEXTBOX_MULTILINE
is not set.
.It Fn textbox-prechg "void"
The string is about to be modified.
.It Fn textbox-postchg "void"
The string was just modified.
.El
.Sh EXAMPLES
The following code fragment binds a
.Nm
to a string contained in a fixed-size buffer:
.Pp
.Bd -literal -offset indent
char name[32];
AG_Textbox *tb;

tb = AG_TextboxNew(parent, 0, "Name: ");
AG_TextboxBindUTF8(tb, name, sizeof(name));
.Ed
.Pp
As is the case with all widgets, a default binding (residing in the widget
structure) is provided.
The following code uses
.Fn AG_TextboxPrintf
to set the value of the default binding, and
.Fn AG_TextboxDupString
to retrieve a pointer to it:
.Pp
.Bd -literal -offset indent
AG_Textbox *tb;
char *value_ptr;

tb = AG_TextboxNew(parent, 0, "Value: ");
AG_TextboxPrintf(tb, "Foo");
value_ptr = AG_TextboxDupString(tb);
.Ed
.Pp
Note that the default binding is limited to
.Dv AG_TEXTBOX_STRING_MAX
bytes in size.
.Pp
Also see
.Pa demos/textbox
in the Agar source distribution.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Text 3 ,
.Xr AG_Tlist 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
It was mostly rewritten as
.Xr AG_Editable 3
was added in Agar 1.3.2.