AG_TEXTBOX(3)

NAME
AG_Textbox - agar text editor widget

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 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
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.

SEE ALSO
AG_Intro(3), AG_Text(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3), AG_Window(3)

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.