Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_TEXTBOX(3)	       FreeBSD 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 (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 optimiza-
				tions (i.e., periodic redrawing	and character
				set conversions	are avoided).

     AG_TEXTBOX_PASSWORD	Password-style entry where characters are hid-
				den.  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_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	ren-
				ders the use of	AG_TextboxSizeHint() unneces-
				sary.

     AG_TEXTBOX_VFILL		Expand vertically in parent (equivalent	to in-
				voking AG_ExpandVert(3)).  This	flag is	recom-
				mended 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 com-
     plete list	of supported encodings).

     The AG_EditableBindText() function	binds the AG_Textbox to	a multilin-
     gual, 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 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_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 fail-
     ure.

     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	posi-
     tion 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)

     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	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).  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 in-
     stead 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	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);

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

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 rewrit-
     ten as AG_Editable(3) was added in	Agar 1.3.2.  Support for dynamically-
     resized text buffers was added in Agar 1.4.0.

FreeBSD	13.0			August 21, 2002			  FreeBSD 13.0

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://www.freebsd.org/cgi/man.cgi?query=AG_Textbox&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help