NAME

SYNOPSIS

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

DESCRIPTION

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

INITIALIZATION

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

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_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 AG_TEXTBOX_STATIC flag 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

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

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

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

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.

SEE ALSO

HISTORY