AG_Textbox widget implements text edition.
AG_Textbox may be bound to a fixed-size buffer containing a "C" string (a NUL-terminated string)
or a dynamically-sized
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 in AG_Editable(3). The AG_Textbox widget itself only acts as a container for an AG_Editable (adding an optional text label, scrollbars and buttons). Direct buffer-access routines are available in AG_Editable(3).
|AG_Object(3)-> AG_Widget(3)-> AG_Textbox.|
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_TextboxBindUTF8() and AG_TextboxBindASCII() connect a textbox to a buffer containing Unicode or US-ASCII, respectively. size is the size of the buffer in bytes (which must include space for the terminating NUL).
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).
AG_EditableBindText() connects the AG_Textbox to a AG_TextElement(3) object, which can represent text in different languages.
The AG_EditableSetLang() function selects the specified language for the current AG_TextElement(3).
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_TextboxSetPlaceholder() sets the "place holder" text to display when the buffer is empty. An argument of NULL disables placeholder text.
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.
AG_TextboxAutocomplete() sets up an autocomplete routine fn, which will be passed a pointer to an AG_Tlist(3) as first argument (and a pointer to the AG_Editable(3) instance as SELF). The autocomplete routine is expected to populate the tlist with suggestions based on the current buffer contents. If the fn argument is NULL, disable autocomplete (closing any active windows). If an autocomplete context has already been configured, only its function and arguments are updated (and any active timers are cancelled). If non-NULL, fnArgs indicates additional AG_Event(3) style arguments to be passed to the autocomplete routine.
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 has occurred). 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.
AG_Textbox widget provides the following bindings:
AG_Textbox widget generates the following events:
The following code fragment binds an
AG_Textbox to a fixed-size buffer (which accepts UTF-8 encoding):
When no specific binding is provided (as in the following case), AG_Textbox uses an internal, built-in text buffer:
An AG_TextElement(3) can accomodate a potentially large, dynamically-allocated string:
The following code fragment sets up a simple autocomplete routine:
|AG_Intro(3), AG_Editable(3), AG_Text(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3), AG_Window(3)|
|An AG_Textbox widget first appeared in Agar 1.0. It was rewritten as a front-end to AG_Editable(3) in Agar 1.3.2. Support for dynamically-resized text buffers was added in Agar 1.4.0. AG_TextboxAutocomplete() and AG_TEXTBOX_RETURN_BUTTON appeared in Agar 1.6.0. AG_TEXTBOX_UPPERCASE and AG_TEXTBOX_LOWERCASE appeared in Agar 1.6.0. The former AG_TEXTBOX_NOEMACS flag was renamed AG_TEXTBOX_NO_KILL_YANK and AG_TEXTBOX_NOLATIN1 was renamed AG_TEXTBOX_NO_ALT_LATIN1 in Agar 1.6.0. Clipboard integration, AG_EditableAutocomplete() and AG_EditableCatString() appeared in Agar 1.6.0.|