|
Note: The Agar manual pages follow certain conventions, notably
concerning function return values. Please read
AG_Intro(3)
first.
SYNOPSIS
#include <agar/core.h>
#include <agar/gui.h>
|
DESCRIPTION
|
The
AG_Editable widget provides low-level text input functionality for widgets such as
AG_Textbox(3) and
AG_Table(3). It allows the user to edit UTF-8 encoded text in single-line or multi-line mode.
|
INHERITANCE HIERARCHY
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_EditableSetStatic (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_EditableSetFont (AG_Editable *ed, AG_Font *font)
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_STATIC | By default, the contents of the buffer may be modified directly, and
AG_Editable will reflect the changes immediately.
This involves frequent UTF-8 conversions, and requires the widget to be
redrawn periodically.
AG_EDITABLE_STATIC indicates that it is safe to assume that the contents of the buffer
will not change under the widget's feet.
Pass this flag at initialization, or use
AG_EditableSetStatic() to set/unset this mode at runtime.
| | 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_NOWORDSEEK | Disable the emacs-style ALT-f and ALT-b keys which conflict with traditional
LATIN-1 combinations.
| | AG_EDITABLE_NOLATIN1 | Disable traditional LATIN-1 key combinations.
| | 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 widget to a text buffer in UTF-8 or plain ASCII encoding,
respectively.
The
bufferSize argument indicates the complete size of the buffer in bytes.
The
AG_EditableSetStatic() function enables or disables static optimizations at runtime (see
AG_EDITABLE_STATIC flag description).
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_EditableSetFont() configures an alternate font (see
AG_FetchFont(3)). It is also legal to modify the
font pointer of the
AG_Editable object (see
STRUCTURE DATA).
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.
|
CURSOR MANIPULATION
int AG_EditableMapPosition (AG_Editable *ed, int x, int y, int *pos, int absolute)
int AG_EditableMoveCursor (AG_Editable *ed, int x, int y, int absolute)
int AG_EditableGetCursorPos (AG_Editable *ed)
int AG_EditableSetCursorPos (AG_Editable *ed, int pos)
|
The
AG_EditableMapPosition() function translates absolute coordinates (such as display coordinates)
x and
y in pixels to a position in the text buffer and return this position into
pos. The function returns -1 or 1 if the cursor lies before or after the end
of the string, respectively.
If
absolute if 1, y coordinates outside of the widget area are allowed.
AG_EditableMoveCursor() moves the text cursor to the position closest to the specified pixel coordinates
mx and
Fy my(in the widget's local coordinate system).
If
absolute if 1, y coordinates outside of the widget area are allowed.
AG_EditableGetCursorPos() returns the current position of the cursor in the buffer.
Under multithreading, the return value is only valid as long as the widget is
locked.
AG_EditableSetCursorPos() tries to move the cursor to the specified position in the string, after
bounds checking is done.
If
pos is -1, the cursor is moved to the end of the string.
AG_EditableSetCursorPos() returns the new position of the cursor.
|
TEXT MANIPULATION
void AG_EditablePrintf (AG_Editable *ed, const char *fmt, ...)
void AG_EditableSetString (AG_Editable *ed, const char *s)
void AG_EditableSetStringUCS4 (AG_Editable *ed, const Uint32 *s)
void AG_EditableClearString (AG_Editable *ed)
char * AG_EditableDupString (AG_Editable *ed)
Uint32 * AG_EditableDupStringUCS4 (AG_Editable *ed)
size_t AG_EditableCopyString (AG_Editable *ed, char *dst, size_t dst_size)
void AG_EditableBufferChanged (AG_Editable *ed)
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_EditableSetStringUCS4() accepts a string in UCS-4 encoding.
AG_EditableClearString() clears the contents of the buffer.
The
AG_EditableDupString() function returns a copy of the text buffer (with terminating NUL).
The
AG_EditableDupStringUCS4() variant returns an UCS-4 string (also with terminating NUL).
The
AG_EditableCopyString() function copies up to
dst_size - 1 bytes from the text buffer
dst, NUL-terminating the result and returning the number of bytes that would
have been copied if
dst_size was unlimited.
The
AG_EditableCopyStringUCS4() variant operates on an UCS-4 buffer instead.
The
AG_EditableBufferChanged() function signals an outside change in the buffer contents.
It is only useful if the
Nm AG_EDITABLE_STATICflag is set.
AG_EditableInt(), AG_EditableFlt() and
AG_EditableDbl() 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_Editable widget provides the following bindings:
| char *string | Text buffer using UTF-8 encoding.
|
|
EVENTS
The
AG_Editable widget reacts to the following events:
| mouse-button-down | Move focus to the widget.
Position the cursor at a specific position.
| | mouse-motion | Move the cursor and scroll.
| | key-down | Perform the action that the current keymap associates with this key.
|
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:
| AG_Font *font | Alternate font (if NULL, the default font is used).
If calling
AG_EditableSetFont() is not convenient, it is legal to modify this pointer at run time.
|
|
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
demos/textbox in the Agar source distribution.
|
SEE ALSO
HISTORY
|
