.\" Copyright (c) 2008 Hypertriton, Inc. <http://hypertriton.com/>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 8, 2008
.Dt AG_EDITABLE 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Editable
.Nd agar text input widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
widget provides low-level text input functionality for widgets such as
.Xr AG_Textbox 3
and
.Xr AG_Table 3 .
It allows the user to edit UTF-8 encoded text in single-line or multi-line mode.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Editable *"
.Fn AG_EditableNew "AG_Widget *parent" "Uint flags"
.Pp
.Ft "void"
.Fn AG_EditableBindUTF8 "AG_Editable *ed" "char *buffer" "size_t bufferSize"
.Pp
.Ft "void"
.Fn AG_EditableBindASCII "AG_Editable *ed" "char *buffer" "size_t bufferSize"
.Pp
.Ft void
.Fn AG_EditableSetStatic "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_EditableSetPassword "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_EditableSetIntOnly "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_EditableSetFltOnly "AG_Editable *ed" "int enable"
.Pp
.Ft void
.Fn AG_EditableSizeHint "AG_Editable *ed" "const char *text"
.Pp
.Ft void
.Fn AG_EditableSizeHintPixels "AG_Editable *ed" "Uint w" "Uint h"
.Pp
.Ft void
.Fn AG_EditableSizeHintLines "AG_Editable *ed" "Uint nLines"
.Pp
.nr nS 0
The
.Fn AG_EditableNew
function allocates, initializes, and attaches a new
.Nm
widget.
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_EDITABLE_ABANDON_FOCUS "
.It 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.
.It AG_EDITABLE_STATIC
Enable some important optimizations based on the assumption that the contents
of the buffer will not change under the widget's feet.
The default behavior makes no such assumption.
Use
.Fn AG_EditableSetStatic
to change at runtime.
.It AG_EDITABLE_PASSWORD
Password-style entry where characters are hidden.
Use
.Fn AG_EditableSetPassword
to change at runtime.
.It AG_EDITABLE_ABANDON_FOCUS
Arrange for the widget to abandon its focus when the return key is pressed.
.It AG_EDITABLE_INT_ONLY
Restricts input to integers only.
Use
.Fn AG_EditableSetIntOnly
to change at runtime.
.It 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
.Fn AG_EditableSetFltOnly
to change at runtime.
.It AG_EDITABLE_CATCH_TAB
Cause tabs to be entered literally into the string (by default, the tab
key moves focus to the next widget).
.It AG_EDITABLE_NOSCROLL
The view is normally scrolled automatically such that the cursor is always
visible.
This flag disables this behavior.
.It AG_EDITABLE_NOSCROLL_ONCE
Prevents automatic scrolling like
.Dv AG_EDITABLE_NOSCROLL ,
but only for the next rendering cycle.
.It AG_EDITABLE_NOEMACS
Disable emacs-style function keys.
.It AG_EDITABLE_NOWORDSEEK
Disable the emacs-style ALT-f and ALT-b keys which conflict with traditional
LATIN-1 combinations.
.It AG_EDITABLE_NOLATIN1
Disable traditional LATIN-1 key combinations.
.El
.Pp
The
.Fn AG_EditableBindUTF8
and
.Fn AG_EditableBindASCII
functions bind the widget to a text buffer in UTF-8 or plain ASCII encoding,
respectively.
The
.Fa bufferSize
argument indicates the complete size of the buffer in bytes.
.Pp
The
.Fn AG_EditableSetStatic
function enables or disables static optimizations at runtime (see
.Dv AG_EDITABLE_STATIC
flag description).
.Pp
The
.Fn AG_EditableSetPassword
function enables or disables password-type input, where characters are
substituted for
.Sq *
in the display.
.Pp
.Fn AG_EditableSetIntOnly
restricts input to integers (see flags)
.Fn AG_EditableSetFltOnly
restricts input to real numbers (see flags).
.Pp
.Fn AG_EditableSizeHint
requests that the initial geometry of
.Fa ed
is to be sufficient to display the string
.Fa text
in its entirety.
The
.Fn AG_EditableSizeHintPixels
variant accepts arguments in pixels.
.Fn AG_EditableSizeHintLines
accepts a line count.
.Sh CURSOR MANIPULATION
.nr nS 1
.Ft int
.Fn AG_EditableMapPosition "AG_Editable *ed" "int x" "int y" "int *pos" "int absolute"
.Pp
.Ft int
.Fn AG_EditableMoveCursor "AG_Editable *ed" "int x" "int y" "int absolute"
.Pp
.Ft int
.Fn AG_EditableGetCursorPos "AG_Editable *ed"
.Pp
.Ft int
.Fn AG_EditableSetCursorPos "AG_Editable *ed" "int pos"
.Pp
.nr nS 0
The
.Fn AG_EditableMapPosition
function translates absolute coordinates (such as display coordinates)
.Fa x
and
.Fa y
in pixels to a position in the text buffer and return this position into
.Fa pos .
The function returns -1 or 1 if the cursor lies before or after the end
of the string, respectively.
If
.Fa absolute
if 1, y coordinates outside of the widget area are allowed.
.Pp
.Fn 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.
.Pp
.Fn AG_EditableSetCursorPos
tries to move the cursor to the specified position in the string, after
bounds checking is done.
If
.Fa pos
is -1, the cursor is moved to the end of the string.
.Fn AG_EditableSetCursorPos
returns the new position of the cursor.
.Sh TEXT MANIPULATION
.nr nS 1
.Ft void
.Fn AG_EditablePrintf "AG_Editable *ed" "const char *fmt" "..."
.Pp
.Ft void
.Fn AG_EditableSetString "AG_Editable *ed" "const char *s"
.Pp
.Ft void
.Fn AG_EditableSetStringUCS4 "AG_Editable *ed" "const Uint32 *s"
.Pp
.Ft void
.Fn AG_EditableClearString "AG_Editable *ed"
.Pp
.Ft "char *"
.Fn AG_EditableDupString "AG_Editable *ed"
.Pp
.Ft "Uint32 *"
.Fn AG_EditableDupStringUCS4 "AG_Editable *ed"
.Pp
.Ft "size_t"
.Fn AG_EditableCopyString "AG_Editable *ed" "char *dst" "size_t dst_size"
.Pp
.Ft "void"
.Fn AG_EditableBufferChanged "AG_Editable *ed"
.Pp
.Ft int
.Fn AG_EditableInt "AG_Editable *ed"
.Pp
.Ft float
.Fn AG_EditableFlt "AG_Editable *ed"
.Pp
.Ft double
.Fn AG_EditableDbl "AG_Editable *ed"
.Pp
.nr nS 0
The
.Fn AG_EditablePrintf
function uses
.Xr vsnprintf 3
to overwrite the contents of the buffer.
If the
.Fa fmt
argument is NULL, a NUL string is assigned instead.
.Pp
.Fn AG_EditableSetString
overwrites the contents of the buffer with the given string.
The argument may be NULL to clear the string.
.Fn AG_EditableSetStringUCS4
accepts a string in UCS-4 encoding.
.Pp
.Fn AG_EditableClearString
clears the contents of the buffer.
.Pp
The
.Fn AG_EditableDupString
function returns a copy of the text buffer (with terminating NUL).
The
.Fn AG_EditableDupStringUCS4
variant returns an UCS-4 string (also with terminating NUL).
.Pp
The
.Fn AG_EditableCopyString
function copies up to
.Fa dst_size
- 1 bytes from the text buffer
.Fa dst ,
NUL-terminating the result and returning the number of bytes that would
have been copied if
.Fa dst_size
was unlimited.
The
.Fn AG_EditableCopyStringUCS4
variant operates on an UCS-4 buffer instead.
.Pp
The
.Fn AG_EditableBufferChanged
function signals an outside change in the buffer contents.
It is only useful if the
.Nm AG_EDITABLE_STATIC
flag is set.
.Pp
.Fn AG_EditableInt ,
.Fn AG_EditableFlt
and
.Fn AG_EditableDbl
perform conversion of the string contents to
.Ft int
.Ft float
and
.Ft double ,
respectively and return the value.
You probably want to be using the
.Xr AG_Numerical 3
widget instead of these functions.
.Sh BINDINGS
The
.Nm
widget provides the following bindings:
.Pp
.Bl -tag -compact -width "char *string "
.It Va char *string
Text buffer using UTF-8 encoding.
.El
.Sh EVENTS
The
.Nm
widget reacts to the following events:
.Pp
.Bl -tag -compact -width 25n
.It window-mousebuttondown
Move focus to the widget.
Position the cursor at a specific position.
.It window-mousemotion
Move the cursor and scroll.
.It window-keydown
Perform the action that the current keymap associates with this key.
.El
.Pp
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -width 2n
.It Fn editable-return "void"
Return was pressed and
.Dv AG_EDITABLE_MULTILINE
is not set.
.It Fn editable-prechg "void"
The string is about to be modified.
.It Fn editable-postchg "void"
The string was just modified.
.El
.Sh EXAMPLES
The following code fragment binds a
.Nm
to a string contained in a fixed-size buffer:
.Pp
.Bd -literal -offset indent
char name[32];
AG_Editable *ed;

ed = AG_EditableNew(parent, 0);
AG_EditableBindUTF8(ed, name, sizeof(name));
.Ed
.Pp
See
.Pa demos/textbox
in the Agar source distribution.
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Text 3 ,
.Xr AG_Tlist 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
It was mostly rewritten as
.Xr AG_Editable 3
was added in Agar 1.3.2.