<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

The AG_Textbox widget implements text edition. AG_Textbox may be bound to a fixed-size buffer containing a "C" string (i.e., a NUL-terminated string), or a dynamically-sized AG_Text(3) buffer.

The string bound to AG_Textbox may use different encodings (support for US-ASCII, UTF-8 and UCS-4 is built-in, conversion to/from other encodings requires that Agar be built with iconv(3) support).

Most of the functionality of AG_Textbox is actually implemented by the AG_Editable(3) class (the AG_Textbox widget itself simply embeds an AG_Editable along with scrollbars and cosmetics such as text labels). The AG_Editable(3) API also provides direct buffer-access routines for more advanced text processing.

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_TextboxBindEncoded (AG_Textbox *textbox, const char *encoding, char *buffer, size_t bufferSize)

void AG_TextboxBindText (AG_Textbox *textbox, AG_Text *txt)

void AG_TextboxSetLang (AG_Textbox *textbox, enum ag_language lang)

void AG_TextboxSetExcl (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_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_MULTILINGUAL	Allow the user to select different languages from the right-click popup menu (provided the widget is bound to an AG_Text(3) element).
AG_TEXTBOX_EXCL	By default, external changes to the contents of the buffer are allowed and handled in a safe manner (at the cost of frequent character set conversions and periodical redrawing of the widget). If AG_TEXTBOX_EXCL is set, AG_Textbox will assume exclusive access to the buffer, permitting some important optimizations (i.e., periodic redrawing and character set conversions are avoided).
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_NOLATIN1	Disable traditional LATIN-1 key combinations.
AG_TEXTBOX_NOPOPUP	Disable the standard right-click popup menu.
AG_TEXTBOX_READONLY	Make the string read-only. This has the same effect as using AG_WidgetDisable(3), except that the textbox is not grayed out.
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.

AG_TextboxBindEncoded() binds to a fixed-size buffer containing a C string in the specified encoding. Support for the "US-ASCII" and "UTF-8" encodings is built-in, but conversion to other encodings requires that Agar be compiled with iconv(3) support (see iconv_open(3) for the complete list of supported encodings).

The AG_EditableBindText() function binds the AG_Textbox to a multilingual, variable-length AG_Text(3) element.

The AG_EditableSetLang() function selects the specified language for the current AG_Text(3) binding.

The AG_TextboxSetExcl() function sets exclusive access to the buffer. Enable only if the bound string is guaranteed not to change externally (see AG_TEXTBOX_EXCL flag description above).

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_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)

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

int AG_TextboxGetCursorPos (AG_Textbox *textbox)

int AG_TextboxSetCursorPos (AG_Textbox *textbox, int pos)

The AG_TextboxMapPosition() function translates pixel coordinates x and y to a character position within the text buffer. On success, the position is returned into pos. The function returns 0 on success or -1 on failure.

AG_TextboxMoveCursor() moves the text cursor to the position closest to the pixel coordinates mx and my.

AG_TextboxGetCursorPos() returns the current position of the cursor in the buffer. The return value is only valid as long as the widget remains 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_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_TextboxClearString() clears the contents of the buffer.

The AG_TextboxDupString() function returns a copy of the text buffer, as-is. AG_TextboxCopyString() copies the contents of the text buffer to a fixed-size buffer (up to dst_size - 1 bytes will be copied). Returns the number of bytes that would have been copied were dst_size unlimited (i.e., if the return value is >= dst_size, truncation occured). Both AG_TextboxDupString() and AG_TextboxCopyString() return the raw contents of the text buffer, without performing any character set conversion.

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`	Bound fixed-size buffer containing a "C" string (i.e., a NUL-terminated string) in the specified encoding (UTF-8 by default).
`AG_Text *text`	Bound AG_Text(3) element containing an table of variable-length C strings (entries in this table map to different languages).

EVENTS

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_Editable ed**	Pointer to the underlying AG_Editable(3) widget.
*AG_Label lbl**	Pointer to the AG_Label(3) (if any). A call to AG_TextboxSetLabel() will create a new label object.
*AG_Text text**	An initially empty AG_Text(3) object used as the default binding (where AG_TextboxBind*() is not used).

EXAMPLES

The following code fragment binds an AG_Textbox to a fixed-size buffer (which accepts UTF-8 encoding):

char name[32];
AG_Textbox *tb;

tb = AG_TextboxNew(parent, 0, "Name: ");
AG_TextboxBindUTF8(tb, name, sizeof(name));

When no specific binding is provided (as in the following case), AG_Textbox uses an internal, built-in text buffer:

AG_Textbox *tb;
char *s;

tb = AG_TextboxNew(parent, 0, "Value: ");
AG_TextboxPrintf(tb, "Foo");

/* Retrieve the string. */
s = AG_TextboxDupString(tb);

Exclusive access to an AG_Text(3) element is an efficient option for editing potentially large, dynamically-allocated strings:

AG_Text *myLargeText;
AG_Textbox *tb;

myLargeText = AG_TextNew(0);
tb = AG_TextboxNew(parent,
    AG_TEXTBOX_EXCL|AG_TEXTBOX_MULTILINE,
    NULL);
AG_TextboxBindText(tb, myLargeText);

Also see tests/textbox.c and tests/charsets.c 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.