AG_Editable widget implements low-level text edition.
AG_Editable may be bound to a fixed-size buffer containing a "C" string (i.e., a
NUL-terminated string), or a dynamically-sized
The string bound to AG_Editable 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 applications will not use AG_Editable directly, and instead use AG_Textbox(3) (which adds scrollbars and cosmetics such as text labels). The bare-bones AG_Editable widget is designed to be easily embeddable into other widgets.
The API also includes methods for accessing the working buffer directly (see BUFFER ACCESS ROUTINES section below). This provides developers with a consistent interface for extending the low-level functionality of the widget (for example, the Copy/Paste/Delete or "Select All" functions could be implemented externally in this way).
|AG_Object(3)-> AG_Widget(3)-> AG_Editable.|
The AG_EditableNew() function allocates, initializes, and attaches a new AG_Editable widget. Acceptable flags include:
The AG_EditableBindUTF8() and AG_EditableBindASCII() functions bind the AG_Editable to a fixed-size buffer containing a C string in UTF-8 or US-ASCII encoding, respectively. The bufferSize argument indicates the complete size of the buffer in bytes.
AG_EditableBindEncoded() 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_Editable 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_EditableSetExcl() function sets exclusive access to the buffer. Enable only if the bound string is guaranteed not to change externally (see AG_EDITABLE_EXCL flag description above).
The AG_EditableSetPassword() function enables or disables password-type input, where characters are substituted for " * " in the display.
AG_EditableSetWordWrap() enables/disable word wrapping.
AG_EditableSetIntOnly() restricts input to integers (see flags) AG_EditableSetFltOnly() restricts input to real numbers (see flags).
AG_EditableSizeHint() requests that the initial geometry of ed is to be sufficient to display the string text in its entirety. The AG_EditableSizeHintPixels() variant accepts arguments in pixels. AG_EditableSizeHintLines() accepts a line count.
STRING UTILITY ROUTINES
The AG_EditablePrintf() function uses vsnprintf(3) to overwrite the contents of the buffer. If the fmt argument is NULL, a NUL string is assigned instead.
AG_EditableSetString() overwrites the contents of the buffer with the given string. The argument may be NULL to clear the string.
AG_EditableClearString() clears the contents of the buffer.
The AG_EditableDupString() function returns a copy of the text buffer, as-is. If insufficient memory is available, NULL is returned. AG_EditableCopyString() 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_EditableDupString() and AG_EditableCopyString() return the raw contents of the text buffer, without performing any character set conversion.
AG_EditableInt(), AG_EditableFlt() and AG_EditableDbl() perform conversion of the string contents to int float and double, respectively and return the value. Note that the AG_Numerical(3) widget is usually a better option than AG_Editable for editing numbers.
BUFFER ACCESS ROUTINES
CURSOR CONTROL ROUTINES
The AG_EditableMapPosition() 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_EditableMoveCursor() moves the text cursor to the position closest to the pixel coordinates mx and my.
AG_EditableGetCursorPos() returns the current position of the cursor in the text. The return value is only valid as long as the widget remains locked. The position can also be retrieved from the pos variable (see STRUCTURE DATA ) .
AG_EditableSetCursorPos() tries to move the cursor to the specified position in the string (bounds checking is performed). If the pos argument is -1, the cursor is moved to the end of the string. The new position of the cursor is returned.
AG_Editable widget provides the following bindings:
AG_Editable widget generates the following events:
The following code fragment binds a
AG_Editable to a string contained in a fixed-size buffer:
See tests/textbox.c and tests/charsets.c in the Agar source distribution.
|AG_Intro(3), AG_Text(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3), AG_Window(3)|
|The AG_Editable widget first appeared in Agar 1.0. It was mostly rewritten as AG_Editable(3) was added in Agar 1.3.2. The clipboard and direct buffer access routines were added in Agar 1.4.2.|