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

FreeBSD Manual Pages

  
 
  

home | help
AG_EDITABLE(3)	       FreeBSD 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_Text(3) buffer.

     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).

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, size_t
     bufferSize)

     void AG_EditableBindASCII(AG_Editable *ed,	char *buffer, size_t
     bufferSize)

     void AG_EditableBindEncoded(AG_Editable *ed, const	char *encoding,	char
     *buffer, size_t bufferSize)

     void AG_EditableBindText(AG_Editable *ed, AG_Text *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)

     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 horizontal and
				 vertical scrollbars to	appear if the text is
				 larger	than the display area.

     AG_EDITABLE_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_EDITABLE_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_EDITABLE_EXCL is set,
				 AG_Editable will assume exclusive access to
				 the buffer, permitting	some important opti-
				 mizations (i.e., periodic redrawing and char-
				 acter set conversions are avoided).

     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 runtime.

     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_CATCH_TAB	 Cause tabs to be entered literally into the
				 string	(by default, the tab key moves focus
				 to the	next widget).

     AG_EDITABLE_NOSCROLL	 The view is normally scrolled automatically
				 such that the cursor is always	visible.  This
				 flag disables this behavior.

     AG_EDITABLE_NOSCROLL_ONCE	 Prevents automatic scrolling like
				 AG_EDITABLE_NOSCROLL, but only	for the	next
				 rendering cycle.

     AG_EDITABLE_NOEMACS	 Disable emacs-style function keys.

     AG_EDITABLE_NOLATIN1	 Disable traditional LATIN-1 key combinations.

     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 (equivalent to
				 invoking AG_ExpandHoriz(3)).  This flag ren-
				 ders the use of AG_EditableSizeHint() unnec-
				 essary.

     AG_EDITABLE_VFILL		 Expand	vertically in parent (equivalent to
				 invoking AG_ExpandVert(3)).  This flag	ren-
				 ders the use of AG_EditableSizeHint() unnec-
				 essary.

     AG_EDITABLE_EXPAND		 Shorthand for
				 AG_EDITABLE_HFILL|AG_EDITABLE_VFILL.

     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 com-
     plete 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 com-
     plete list	of supported encodings).

     The AG_EditableBindText() function	binds the AG_Editable 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_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
     void AG_EditablePrintf(AG_Editable	*ed, const char	*fmt, ...)

     void AG_EditableSetString(AG_Editable *ed,	const char *s)

     void AG_EditableClearString(AG_Editable *ed)

     char * AG_EditableDupString(AG_Editable *ed)

     size_t AG_EditableCopyString(AG_Editable *ed, char	*dst, size_t 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 con-
     tents of the buffer.  If the fmt argument is NULL,	a NUL string is	as-
     signed 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 con-
     tents of the text buffer, without performing any character	set conver-
     sion.

     AG_EditableInt(), AG_EditableFlt()	and AG_EditableDbl() perform conver-
     sion of the string	contents to int	float and double, respectively and re-
     turn 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,	Uint32
     *ins, size_t nIns)

     int AG_EditableCut(AG_Editable *ed, AG_EditableBuffer *buf,
     AG_EditableClipboard *cb)

     void AG_EditableCopyChunk(AG_Editable *ed,	AG_EditableClipboard *cb)

     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	inter-
     nal, 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) */
	     Uint32 *s;			  /* String buffer (UCS-4 encoding) */
	     size_t len;		  /* String length (chars) */
	     size_t 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 buf-
     fer.  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,	reinitializing
     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 argument.
     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 clipboard
     (the AG_EditableCut() variant subsequently	deletes	the selection).
     AG_EditablePaste()	pastes the contents of the clipboard to	the current
     cursor position.  AG_EditableDelete() deletes the current selection, 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	posi-
     tion 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 posi-
     tion 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.

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_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_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.

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_Text(3) object 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_Text(3) bind-
			     ings only).  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 tests/textbox.c and tests/charsets.c in the Agar source distribution.

SEE ALSO
     AG_Intro(3), AG_Text(3), AG_TextElement(3), AG_Tlist(3), AG_Widget(3),
     AG_Window(3)

HISTORY
     The AG_Editable widget first appeared in Agar 1.0.	 It was	mostly rewrit-
     ten 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.

FreeBSD	13.0			January	8, 2008			  FreeBSD 13.0

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

home | help