Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_Textbox widget allows the user to edit UTF-8 encoded text. It provides the basic AG_Editable(3) interface and adds a built-in text label, cosmetics and scrollbars in multiline mode.

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_Textbox.

INITIALIZATION

AG_Textbox * AG_TextboxNew (AG_Widget *parent, Uint flags, const char *format, ...)

AG_Textbox * AG_TextboxNewS (AG_Widget *parent, Uint flags, const char *label)

void AG_TextboxBindUTF8 (AG_Textbox *textbox, char *buffer, size_t bufferSize)

void AG_TextboxBindASCII (AG_Textbox *textbox, char *buffer, size_t bufferSize)

void AG_TextboxSetStatic (AG_Textbox *textbox, int enable)

void AG_TextboxSetPassword (AG_Textbox *textbox, int enable)

void AG_TextboxSetWordWrap (AG_Textbox *textbox, int enable)

void AG_TextboxSetIntOnly (AG_Textbox *textbox, int enable)

void AG_TextboxSetFltOnly (AG_Textbox *textbox, int enable)

void AG_TextboxSetFont (AG_Textbox *textbox, AG_Font *font)

void AG_TextboxSetLabel (AG_Textbox *textbox, const char *format, ...)

void AG_TextboxSetLabelS (AG_Textbox *textbox, const char *label)

void AG_TextboxSizeHint (AG_Textbox *textbox, const char *text)

void AG_TextboxSizeHintPixels (AG_Textbox *textbox, Uint w, Uint h)

void AG_TextboxSizeHintLines (AG_Textbox *textbox, Uint nLines)

The AG_TextboxNew() function allocates, initializes, and attaches a new AG_Textbox widget. The optional string argument specifies a text label to display at the left of the textbox. Acceptable flags include:

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.
AG_TEXTBOX_STATIC	By default, the contents of the buffer may be modified directly, and AG_Textbox will reflect the changes immediately. This involves frequent UTF-8 conversions, and requires the widget to be redrawn periodically. AG_TEXTBOX_STATIC indicates that it is safe to assume that the contents of the buffer will not change under the widget's feet. Pass this flag at initialization, or use AG_EditableSetStatic() to set/unset this mode at runtime.
AG_TEXTBOX_PASSWORD	Password-style entry where characters are hidden. AG_TextboxSetPassword() sets this flag.
AG_TEXTBOX_ABANDON_FOCUS	Arrange for the widget to abandon its focus when the return key is pressed.
AG_TEXTBOX_INT_ONLY	Restricts input to valid integers only. Use AG_TextboxSetIntOnly() to change at runtime.
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 AG_TextboxSetFltOnly() to change at runtime.
AG_TEXTBOX_CATCH_TAB	Cause tabs to be entered literally into the string (by default, the tab key moves focus to the next widget).
AG_TEXTBOX_NOEMACS	Disable emacs-style function keys.
AG_TEXTBOX_NOWORDSEEK	Disable the emacs-style ALT-f and ALT-b keys which conflict with traditional LATIN-1 combinations.
AG_TEXTBOX_NOLATIN1	Disable traditional LATIN-1 key combinations.
AG_TEXTBOX_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)). This flag renders the use of AG_TextboxSizeHint() unnecessary.
AG_TEXTBOX_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)). This flag is recommended for multi-line text as an alternative to calling AG_TextboxSizeHintLines().
AG_TEXTBOX_EXPAND	Shorthand for AG_TEXTBOX_HFILL\|AG_TEXTBOX_VFILL.

The AG_TextboxBindUTF8() and AG_TextboxBindASCII() functions bind the textbox to a text buffer in UTF-8 or plain ASCII encoding, respectively. The bufferSize argument indicates the complete size of the buffer in bytes.

The AG_TextboxSetStatic() function enables or disables static optimizations at runtime (see AG_TEXTBOX_STATIC flag description).

The AG_TextboxSetPassword() function enables/disables password-type input, where characters are substituted for " * " in the display.

AG_TextboxSetWordWrap() enables/disable word wrapping.

AG_TextboxSetIntOnly() restricts input to integers (see flags) AG_TextboxSetFltOnly() restricts input to real numbers (see flags).

AG_TextboxSetFont() configures an alternate font (see AG_FetchFont(3)). It is also legal to modify the font pointer of the AG_Textbox object (see STRUCTURE DATA).

AG_TextboxSetLabel() changes the current label text to the specified string.

AG_TextboxSizeHint() requests that the initial geometry of textbox is to be sufficient to display the string text in its entirety. The AG_TextboxSizeHintPixels() variant accepts arguments in pixels. AG_TextboxSizeHintLines() accepts a number of lines.

CURSOR MANIPULATION

int AG_TextboxMapPosition (AG_Textbox *textbox, int x, int y, int *pos, int absolute)

void AG_TextboxMoveCursor (AG_Textbox *textbox, int x, int y, int absolute)

int AG_TextboxGetCursorPos (AG_Textbox *textbox)

int AG_TextboxSetCursorPos (AG_Textbox *textbox, int pos)

The AG_TextboxMapPosition() function translates absolute coordinates (such as display coordinates) x and y in pixels to a position in the text buffer and return this position into pos. The function returns -1 or 1 if the cursor lies before or after the end of the string, respectively. If absolute if 1, y coordinates outside of the widget area are allowed.

AG_TextboxMoveCursor() moves the text cursor to the position closest to the specified pixel coordinates mx and Fy my(in the widget's local coordinate system). If absolute if 1, y coordinates outside of the widget area are allowed.

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.

AG_TextboxSetCursorPos() tries to move the cursor to the specified position in the string, after bounds checking is done. If pos is -1, the cursor is moved to the end of the string. AG_TextboxSetCursorPos() returns the new position of the cursor.

TEXT MANIPULATION

void AG_TextboxPrintf (AG_Textbox *textbox, const char *fmt, ...)

void AG_TextboxSetString (AG_Textbox *textbox, const char *s)

void AG_TextboxSetStringUCS4 (AG_Textbox *textbox, const Uint32 *s)

void AG_TextboxClearString (AG_Textbox *textbox)

char * AG_TextboxDupString (AG_Textbox *textbox)

size_t AG_TextboxCopyString (AG_Textbox *textbox, char *dst, size_t dst_size)

void AG_TextboxBufferChanged (AG_Textbox *textbox)

int AG_TextboxInt (AG_Textbox *textbox)

float AG_TextboxFlt (AG_Textbox *textbox)

double AG_TextboxDbl (AG_Textbox *textbox)

The AG_TextboxPrintf() function uses vsnprintf(3) to overwrite the contents of the buffer. If the fmt argument is NULL, a NUL string is assigned instead.

AG_TextboxSetString() overwrites the contents of the buffer with the given string. The argument may be NULL to clear the string. AG_TextboxSetStringUCS4() accepts a string in UCS-4 encoding.

AG_TextboxClearString() clears the contents of the buffer.

The AG_TextboxDupString() function returns a copy of the text buffer.

The AG_TextboxCopyString() function copies up to dst_size - 1 bytes from the text buffer dst, NUL-terminating the result and returning the number of bytes that would have been copied if dst_size was unlimited.

The AG_TextboxBufferChanged() function signals an outside change in the buffer contents. It is only useful if the Nm AG_TEXTBOX_STATICflag is set.

AG_TextboxInt(), AG_TextboxFlt() and AG_TextboxDbl() perform conversion of the string contents to int float and double, respectively and return the value. You probably want to be using the AG_Numerical(3) widget instead of these functions.

BINDINGS

The AG_Textbox widget provides the following bindings:

char *string

Text buffer using UTF-8 encoding.

EVENTS

The AG_Textbox widget reacts to the following events:

mouse-button-down	Move focus to the widget. Position the cursor at a specific position.
mouse-motion	Move the cursor and scroll.
key-down	Perform the action that the current keymap associates with this key.

The AG_Textbox widget generates the following events:

textbox-return (void)	Return was pressed and AG_TEXTBOX_MULTILINE is not set.
textbox-prechg (void)	The string is about to be modified.
textbox-postchg (void)	The string was just modified.

STRUCTURE DATA

For the AG_Textbox object:

*AG_Label lbl**	Pointer to the textbox's associated AG_Label(3). If no text label was given, this is a NULL pointer. A call to AG_TextboxSetLabel() will create a new label object.
*AG_Font font**	Alternate font (if NULL, the default font is used). If calling AG_TextboxSetFont() is not convenient, it is legal to modify this pointer at run time.

EXAMPLES

The following code fragment binds an AG_Textbox to a string contained in a fixed-size buffer:

char name[32];
AG_Textbox *tb;
tb = AG_TextboxNew(parent, 0, "Name: ");
AG_TextboxBindUTF8(tb, name, sizeof(name));

As is the case with all widgets, a "default" binding (limited to AG_TEXTBOX_STRING_MAX bytes) is provided. The following code uses and AG_TextboxDupString() on the default binding:

AG_Textbox *tb;
char *value_ptr;
tb = AG_TextboxNew(parent, 0, "Value: ");
AG_TextboxPrintf(tb, "Foo");
value_ptr = AG_TextboxDupString(tb);

Also see demos/textbox in the Agar source distribution.

HISTORY

The AG_Textbox widget first appeared in Agar 1.0. It was mostly rewritten as AG_Editable(3) was added in Agar 1.3.2. Support for dynamically-resized text buffers was added in Agar 1.4.0.