FreeBSD Manual Pages
AG_EDITABLE(3) Library Functions Manual AG_EDITABLE(3) NAME AG_Editable -- agar text input widget SYNOPSIS #include <agar/core.h> #include <agar/gui.h> DESCRIPTION The 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 AG_TextElement(3). 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 en- codings requires that Agar be built with iconv(3) support). The AG_Editable widget is a "low-level" editor which implements an ed- itable field (single or multi-line), but with no decorations or scrolling ability. The more commonly used AG_Textbox(3) widget itself embeds an AG_Editable and also adds decorations, scrollbars and a text label. The AG_Editable 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, "Copy", "Paste", "Delete" and "Select All" functions can be implemented externally in this way). INHERITANCE HIERARCHY AG_Object(3) -> AG_Widget(3) -> AG_Editable. INITIALIZATION AG_Editable * AG_EditableNew(AG_Widget *parent, Uint flags) void AG_EditableBindUTF8(AG_Editable *ed, char *buffer, AG_Size bufferSize) void AG_EditableBindASCII(AG_Editable *ed, char *buffer, AG_Size bufferSize) void AG_EditableBindEncoded(AG_Editable *ed, const char *encoding, char *buffer, AG_Size bufferSize) void AG_EditableBindText(AG_Editable *ed, AG_TextElement *txt) void AG_EditableSetLang(AG_Editable *ed, enum ag_language lang) void AG_EditableSetExcl(AG_Editable *ed, int enable) void AG_EditableSetPassword(AG_Editable *ed, int enable) void AG_EditableSetWordWrap(AG_Editable *ed, int enable) void AG_EditableSetIntOnly(AG_Editable *ed, int enable) void AG_EditableSetFltOnly(AG_Editable *ed, int enable) void AG_EditableSizeHint(AG_Editable *ed, const char *text) void AG_EditableSizeHintPixels(AG_Editable *ed, Uint w, Uint h) void AG_EditableSizeHintLines(AG_Editable *ed, Uint nLines) void AG_EditableAutocomplete(AG_Editable *ed, void (*fn)(AG_Event *), const char *fnArgs, ...) void AG_EditableCloseAutocomplete(AG_Editable *ed) The AG_EditableNew() function allocates, initializes, and attaches a new AG_Editable widget. Acceptable flags include: AG_EDITABLE_MULTILINE Causes newlines to be entered literally into the string, and arranges for horizon- tal and vertical scrollbars to appear if the text is larger than the display area. AG_EDITABLE_WORDWRAP Enable word wrapping in multiline mode. AG_EDITABLE_MULTILINGUAL Allow the user to select different lan- guages from the right-click popup menu (provided the widget is bound to an AG_TextElement(3)). AG_EDITABLE_EXCL By default, external changes to the con- tents 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_EDITABLE_EXCL is set, AG_Editable will assume exclusive access to the buffer, per- mitting some important optimizations (i.e., periodic redrawing and character set con- versions are avoided). AG_EDITABLE_UPPERCASE Display all characters in upper-case. AG_EDITABLE_LOWERCASE Display all characters in lower-case. AG_EDITABLE_PASSWORD Password-style entry where characters are hidden. Use AG_EditableSetPassword() to change at runtime. AG_EDITABLE_ABANDON_FOCUS Arrange for the widget to abandon its focus when the return key is pressed. AG_EDITABLE_INT_ONLY Restricts input to integers only. Use AG_EditableSetIntOnly() to change at run- time. AG_EDITABLE_FLT_ONLY Restricts input to floating-point numbers in decimal and scientific notation ("inf" and the Unicode symbol for Infinity may also be used). Use AG_EditableSetFltOnly() to change at runtime. AG_EDITABLE_NUMERICAL Shorthand for AG_EDITABLE_INT_ONLY and AG_EDITABLE_FLT_ONLY. AG_EDITABLE_CATCH_TAB Cause tabs to be entered literally into the string (by default, the tab key moves focus to the next widget). but only for the next rendering cycle. AG_EDITABLE_NO_KILL_YANK Disable Kill (ctrl-K) and Yank (ctrl-Y). AG_EDITABLE_NO_ALT_LATIN1 Disable alt-key mappings to extended Latin-1 characters. AG_EDITABLE_NOPOPUP Disable the standard right-click popup menu. AG_EDITABLE_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_EDITABLE_HFILL Expand horizontally in parent container. AG_EDITABLE_VFILL Expand vertically in parent container. AG_EDITABLE_EXPAND Shorthand for AG_EDITABLE_HFILL | AG_EDITABLE_VFILL. AG_EDITABLE_NO_CLIPPING Disable clipping in the draw function, al- lowing overflow of text beyond the widget's allocated space. Used by container widgets which implement their own clipping (such as AG_Textbox(3) ). 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 re- quires that Agar be compiled with iconv(3) support (see iconv_open(3) for the complete list of supported encodings). AG_EditableBindText() connects the AG_Editable to an AG_TextElement(3). The AG_EditableSetLang() function selects the specified language for the current AG_TextElement(3). 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. AG_EditableAutocomplete() sets up an autocomplete routine fn, which will be passed a pointer to an AG_Tlist(3) as first argument. This routine is expected to populate the tlist with suggestions based on the current buffer contents. If the fn argument is NULL, disable autocom- plete (closing any active windows). If an autocomplete context has al- ready been configured, only its function and arguments are updated (and any active timers are cancelled). If non-NULL, fnArgs indicates addi- tional AG_Event(3) style arguments to be passed to the autocomplete routine. AG_EditableCloseAutocomplete() closes any active autocomplete windows. If there are no autocomplete windows open or an autocomplete context has not been defined then this routine is a no-op. STRING UTILITY ROUTINES void AG_EditablePrintf(AG_Editable *ed, const char *fmt, ...) void AG_EditableSetString(AG_Editable *ed, const char *s) void AG_EditableCatString(AG_Editable *ed, const char *fmt, ...) void AG_EditableCatStringS(AG_Editable *ed, const char *s) void AG_EditableClearString(AG_Editable *ed) char * AG_EditableDupString(AG_Editable *ed) AG_Size AG_EditableCopyString(AG_Editable *ed, char *dst, AG_Size dst_size) int AG_EditableInt(AG_Editable *ed) float AG_EditableFlt(AG_Editable *ed) double AG_EditableDbl(AG_Editable *ed) 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_EditableCatString() appends the given string at the end of the buffer contents. Return 0 on success or -1 if buffer is too small or truncation occurred. 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 has occurred). Both AG_EditableDupString() and AG_EditableCopyString() return the raw contents of the text buffer, without performing any character set con- version. AG_EditableInt(), AG_EditableFlt() and AG_EditableDbl() perform conver- sion 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 AG_EditableBuffer * AG_EditableGetBuffer(AG_Editable *ed) void AG_EditableReleaseBuffer(AG_Editable *ed, AG_EditableBuffer *buf) void AG_EditableClearBuffer(AG_Editable *ed, AG_EditableBuffer *buf) int AG_EditableGrowBuffer(AG_Editable *ed, AG_EditableBuffer *buf, AG_Char *ins, AG_Size nIns) int AG_EditableCut(AG_Editable *ed, AG_EditableBuffer *buf, AG_EditableClipboard *cb) void AG_EditableCopyChunk(AG_Editable *ed, AG_EditableClipboard *cb, AG_Char *s, AG_Size len) int AG_EditableCopy(AG_Editable *ed, AG_EditableBuffer *buf, AG_EditableClipboard *cb) int AG_EditablePaste(AG_Editable *ed, AG_EditableBuffer *buf, AG_EditableClipboard *cb) int AG_EditableDelete(AG_Editable *ed, AG_EditableBuffer *buf) void AG_EditableSelectAll(AG_Editable *ed, AG_EditableBuffer *buf) The AG_EditableGetBuffer() function returns a locked handle to the in- ternal, working buffer associated with an AG_Editable widget. The buffer structure is defined as follows: typedef struct ag_editable_buffer { AG_Variable *var; /* Variable binding (if any) */ AG_Char *s; /* Buffer contents */ AG_Size len; /* Length of string (chars) */ AG_Size maxLen; /* Available buffer size (bytes) */ int reallocable; /* Buffer can be realloc'd */ } AG_EditableBuffer; The contents of s may be modified directly (any change to the effective string length must be reflected in the len field). The AG_EditableReleaseBuffer() function unlocks and releases working buffer. It must be called following the AG_EditableGetBuffer() call, once the caller has finished accessing the buffer. AG_EditableClearBuffer() frees the contents of the buffer, reinitializ- ing to an empty string. The AG_EditableGrowBuffer() function attempts to increase the size of the buffer in order to accomodate the nIns characters in the ins argu- ment. If insufficient space is available (e.g., this is a fixed-size buffer or we ran out of memory), the function fails and returns -1. AG_EditableCopyChunk() copies the specified string of characters to the clipboard. AG_EditableCopy() copies the whole selection to the clip- board (the AG_EditableCut() variant subsequently deletes the selec- tion). AG_EditablePaste() pastes the contents of the clipboard to the current cursor position. AG_EditableDelete() deletes the current se- lection, if any. The return value of those functions is 1 if the buffer has been modified, or 0 if the buffer is unchanged. AG_EditableSelectAll() selects all characters in the buffer. CURSOR CONTROL ROUTINES int AG_EditableMapPosition(AG_Editable *ed, AG_EditableBuffer *buf, int x, int y, int *pos) int AG_EditableMoveCursor(AG_Editable *ed, AG_EditableBuffer *buf, int x, int y) int AG_EditableGetCursorPos(AG_Editable *ed) int AG_EditableSetCursorPos(AG_Editable *ed, AG_EditableBuffer *buf, int pos) 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 po- sition in the string (bounds checking is performed). If the pos argu- ment is -1, the cursor is moved to the end of the string. The new po- sition of the cursor is returned. BINDINGS The AG_Editable 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_TextElement *text Bound AG_TextElement(3). char *placeholder An optional string of text to display whenever the text buffer is empty. EVENTS The AG_Editable widget generates the following events: editable-return(void) Return was pressed and AG_EDITABLE_MULTILINE is not set. editable-prechg(void) The string is about to be modified. editable-postchg(void) The string was just modified. editable-increment(void) Request to increment the number represented by the string (requires AG_EDITABLE_NUMERICAL and AG_EDITABLE_MULTILINE to be unset). editable-decrement(void) Request to decrement the number represented by the string (requires AG_EDITABLE_NUMERICAL and AG_EDITABLE_MULTILINE to be unset). STRUCTURE DATA For the AG_Editable object: int pos Current cursor position (ranging from 0 to the current buffer's len value). int sel Current selection, expressed as an offset from the cursor (0 = there is no selection). AG_Text *text An initially empty AG_TextElement(3) used as the default binding (where AG_EditableBind*() is not used). char *encoding Character set for the bound string. This may be set to "US-ASCII" or "UTF-8" (the default). Other character sets are supported if Agar was compiled with iconv(3) support. enum ag_language lang Currently selected language (for AG_TextElement(3) bindings). Read-only; use AG_EditableSetLang() to change. EXAMPLES The following code fragment binds a AG_Editable to a string contained in a fixed-size buffer: char name[32]; AG_Editable *ed; ed = AG_EditableNew(parent, 0); AG_EditableBindUTF8(ed, name, sizeof(name)); See AG_Textbox(3) for an example autocomplete routine (note that the AG_TextboxAutocomplete() call is an alias for AG_EditableAutocomplete()). SEE ALSO AG_Intro(3), AG_Text(3), AG_Textbox(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3), AG_Window(3) HISTORY An AG_Textbox first appeared in Agar 1.0. It was rewritten as a front- end to AG_Editable(3) in Agar 1.3.2. The clipboard and direct buffer access routines were added in Agar 1.4.2. AG_EDITABLE_UPPERCASE and AG_EDITABLE_LOWERCASE appeared in Agar 1.6.0. The former AG_EDITABLE_NOEMACS flag was renamed AG_EDITABLE_NO_KILL_YANK and AG_EDITABLE_NOLATIN1 was renamed AG_EDITABLE_NO_ALT_LATIN1 in Agar 1.6.0. Clipboard integration, AG_EditableAutocomplete() and AG_EditableCatString() appeared in Agar 1.6.0. Controller support and the "editable-increment" and "editable-decrement" events appeared in Agar 1.7.0. Agar 1.7 December 21, 2022 AG_EDITABLE(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | STRING UTILITY ROUTINES | BUFFER ACCESS ROUTINES | CURSOR CONTROL ROUTINES | BINDINGS | EVENTS | STRUCTURE DATA | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Editable&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>