NAME

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

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

INITIALIZATION

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 character 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 optimizations (i.e., periodic redrawing and character 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 renders the use of AG_EditableSizeHint() unnecessary.

AG_EDITABLE_VFILL

Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)). This flag renders the use of AG_EditableSizeHint() unnecessary.

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

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

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

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

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

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) bindings only). Read-only; use AG_EditableSetLang() to change.

EXAMPLES

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

HISTORY