FreeBSD Manual Pages
AG_TEXTBOX(3) Library Functions Manual 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 (a NUL-terminated string) or a dynamically-sized AG_TextElement(3). 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 encod- ings 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 but- tons). Direct buffer-access routines are available in AG_Editable(3). 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, AG_Size size) void AG_TextboxBindASCII(AG_Textbox *textbox, char *buffer, AG_Size size) void AG_TextboxBindEncoded(AG_Textbox *textbox, const char *encoding, char *buffer, AG_Size size) 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_TextboxSetPlaceholder(AG_Textbox *textbox, const char *fmt, ...) void AG_TextboxSetPlaceholderS(AG_Textbox *textbox, const char *s) 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) void AG_TextboxAutocomplete(AG_Textbox *tb, void (*fn)(AG_Event *), const char *fnArgs, ...) 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_WORDWRAP Enable word wrapping in multiline mode. AG_TEXTBOX_MULTILINGUAL Allow the user to select different languages from the right-click popup menu (provided the widget is bound to an AG_TextElement(3)). AG_TEXTBOX_RETURN_BUTTON Display a RETURN button which generates "textbox-return" when clicked. 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 charac- ter 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 opti- mizations (i.e., periodic redrawing and character set conversions are avoided). AG_TEXTBOX_UPPERCASE Display all characters in upper-case. AG_TEXTBOX_LOWERCASE Display all characters in lower-case. 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 num- bers 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_NO_KILL_YANK Disable Kill (ctrl-K) and Yank (ctrl-Y) functions. AG_TEXTBOX_NO_ALT_LATIN1 Disable alt-key mappings to extended Latin1 characters. 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_NO_SHADING Disable 3D-style shading around the field. AG_TEXTBOX_HFILL Expand horizontally in parent container. AG_TEXTBOX_VFILL Expand vertically in parent container. AG_TEXTBOX_EXPAND Shorthand for AG_TEXTBOX_HFILL | AG_TEXTBOX_VFILL. 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 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_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 in- put, 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. 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 po- sition 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 re- mains locked. AG_TextboxSetCursorPos() tries to move the cursor to the specified po- sition in the string, after bounds checking is done. If pos is -1, the cursor is moved to the end of the string. AG_TextboxSetCursorPos() re- turns 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) AG_Size AG_TextboxCopyString(AG_Textbox *textbox, char *dst, AG_Size 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 con- tents of the buffer. If the fmt argument is NULL, a NUL string is as- signed 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). Re- turns the number of bytes that would have been copied were dst_size un- limited (i.e., if the return value is >= dst_size, truncation has oc- curred). 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 Fixed-size buffer containing a "C" string (a NUL-termi- nated string) in the specified encoding (UTF-8 by de- fault). AG_Text *text Bound AG_TextElement(3), which can represent text in 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_TextElement(3) used as the de- fault 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); An AG_TextElement(3) can accomodate a potentially large, dynamically- allocated string: AG_TextElement *txt; AG_Textbox *tb; txt = AG_TextNew(0); tb = AG_TextboxNew(parent, AG_TEXTBOX_EXCL | AG_TEXTBOX_MULTILINE, NULL); AG_TextboxBindText(tb, txt); The following code fragment sets up a simple autocomplete routine: static void MyAutocomplete(AG_Event *event) { const char *dict[] = { "Apple", "Orange", "Banana", NULL }, **dp; AG_Editable *ed = AG_EDITABLE_SELF(); AG_Tlist *tl = AG_TLIST_PTR(1); char *s, *sp; if ((sp = s = AG_EditableDupString(ed)) == NULL) { return; } while (*sp == ' ') /* Strip leading whitespace */ sp++; AG_TlistBegin(tl); for (dp = dictFirst; *dp != NULL; dp++) { if (sp[0] == '\0' || AG_Strncasecmp(*dp, sp, strlen(sp)) == 0) { AG_TlistAddPtr(tl, NULL, *dp, (void *)*dp); } } AG_TlistEnd(tl); free(s); } AG_Textbox *tb; tb = AG_TextboxNew(NULL, 0, "Fruit: "); AG_TextboxAutocomplete(tb, MyAutocomplete, NULL); SEE ALSO AG_Intro(3), AG_Editable(3), AG_Text(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3), AG_Window(3) HISTORY 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-re- sized 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. Agar 1.7 December 21, 2022 AG_TEXTBOX(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | CURSOR MANIPULATION | TEXT MANIPULATION | 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_Textbox&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>